-
Notifications
You must be signed in to change notification settings - Fork 14
Querying Data with GraphQL
Deep Lynx ships with the ability to query data that you have ingested in previous steps. This capability is still actively under construction, so if you don't see a needed feature in this write up please reach out to the development team to discuss its absence and whether the feature could be something you add.
This guide assumes basic knowledge of querying using GraphQL. You can find a good tutorial and write-up here - https://graphql.org/learn/. You should pay particular attention to how queries are built, how GraphQL returns only the data you explicitly request, and any documentation specific to the language you hope to use to interact with this functionality.
In GraphQL, schema is generally defined prior to running the application. The schema determines what kinds of queries can be made, how they're structured, and what functions they access in the program to populate the users results. The first iteration of this functionality followed this pattern, but we found the system to be unwieldy and hard to understand. Instead, Deep Lynx dynamically generates a schema each time you interact with the GraphQL endpoint for a given container. When you first start up an instance of DeepLynx, the first GraphQL query sent may take a few seconds due to this schema generation. However, after the first query the schema generation is cached for much faster response times.
Currently, the generated schema’s types map 1:1 to a Metatype in the container you are querying. So for example if your ontology had the Car, Maintenance, and Entry Metatypes – your GraphQL Schema would also have a type for Car, Maintenance, and Entry. These types are used for querying nodes with these specific Metatypes. More information on how to accomplish these queries can be found in the next major section.
You can use introspection at any time to get a complete list of all potential types, and other information, at any time. This is useful as your schema might be different from another user’s based on the container you are querying. This is also helpful because we must perform a slight conversion on your Metatype names to make them work with GraphQL – and introspection allows you to see exactly how we might have named your custom Metatype.
Much like normal queries, you would POST your introspection GraphQL query to {{yourURL}}/containers/{{containerID}}/data
- and much like normal queries, your POST body should be a JSON body with the following two fields - query
and variables
. query
is an escaped string containing your GraphQL query. variables
is a JSON object containing any variables which were included in your query.
More information on formatting a query can be found here - https://graphql.org/learn/serving-over-http/.
Here is an example introspective query - this one simply returns a list of all possible GraphQL types by name.
{
__schema {
types {
name
}
}
}
Note: Not all types that are returned by this query are Metatypes. Some might be native GraphQL types, or enumerable types needed by a Metatype. With the updated query layer, there will also be the wrapper types metatypes
, relationships
, and graph_type
, as well as a type for each relationship in the ontoloty. When in doubt, refer back to the container’s ontology to differentiate between what’s a standard GraphQL type, what's a relationship, and what’s a Metatype.
Please keep in mind that this is actively under construction, meaning things may change slightly and new features may be added. We will endeavor to keep this guide up to date, but if in doubt please contact the development team.
Currently (3/25/22), there are three categories in which a user can query in GraphQL. Theses are metatypes
, in which you can request all nodes of a certain metatype, relationships
, in which you can request all edges of a certain metatype relationship, and graph
, in which you can specify a "root node" and "depth" and get all node-edge-node objects in the graph structure that are n
layers away from the root (where n
is the depth specified).
We will not spend a large amount of this guide on how to make a GraphQL request. We feel this topic is covered well in other guides, as well as the official documentation . We follow all standard practices in how a GraphQL query is structured as a JSON object for POSTing to an HTTP endpoint. This guide also assumes that while we display a GraphQL query in its object form, it must be encoded as a string and included in a JSON object as the query
property.
The most important thing to remember is that the endpoint to which you send all GraphQL queries (via HTTP POST request) is the following:
{{yourURL}}/containers/{{yourContainerID}}/data
The primary objective of querying metatypes
is to allow a user to swiftly retrieve a list of all nodes of a given Metatype and which match a set of filters based on that Metatype’s properties, or keys.
The following steps will demonstrate how a user might query and receive nodes of the Requirement type.
A user must know the name of the GraphQL type for “Requirement”. This is done most easily by running the introspective query listed earlier in this page and searching for a type by, or close to, that name. In this case the name of the GraphQL type should be the exact same – “Requirement”. Note: Metatype names that consist of more than one word will have their spaces replaced by the _
character. So “Maintenance Entry” would become “Maintenance_Entry
” in the GraphQL schema. A metatype whose name starts with a number will have _
prepended to its name. So “1 Maintenance” would become “_1_Maintenance
”.
Optional - Just like on the main GraphQL schema, you can run an introspective query on the “Requirement” type to see what fields may exist for you to request and query against. The following query illustrates how to accomplish this. The fields returned from this query represent all valid fields upon which you can filter or request, as well as their datatypes.
{
__type(name: "Requirement") {
name
fields {
name
type {
name
kind
}
}
}
}
You might see the following response (explanation of fields are in comments next to fields)
{
"data": {
"__type": {
"name": "Requirement", # represents which Metatype you queried
"fields": [
{
"name": "_record", # this is a special object which
"type": { # contains metadata about the object
"name": "recordInfo",
"kind": "OBJECT"
}
},
{
"name": "type", # name of the field itself
"type": { # datatype of the field
"name": "String",
"kind": "SCALAR"
}
},
{
"name": "active",
"type": {
"name": "Boolean",
"kind": "SCALAR"
}
},
{
"name": "id",
"type": {
"name": "Float",
"kind": "SCALAR"
}
}
]
}
}
}
We can further interrogate the _record
objects (and any other fields of the kind OBJECT
) using another introspective query based on the type name of these objects:
{
__type(
name: "recordInfo" #name field of "_record" type above
){
fields{
name
type{
name
}
}
}
}
This will allow us to see which sub-fields may be queried in these OBJECT
-typed fields.
The Metatype field names generally map directly to your Metatype’s properties/keys. However, in this case, the names are taken from the Metatype Key’s "property name" field, not the name of the Metatype Key itself. So, in this case, the Requirement Metatype has a field named “Active” and that field's property name is “active” – thus “active” is what you would use to request that field in the return object.
Once a user knows the Metatype they’re querying for and the possible fields, they can then craft the query. Remember that GraphQL only returns the data you explicitly request. This means that if you leave a field off your request, the return value will also omit this field.
The query below will request all possible fields for the “Requirement” Metatype – comments next to the query help explain each part.
NOTE: there is an extra metatypes
wrapper around this query as compared to the original query structure. Adding this layer around your Metatype queries will specify to GraphQL that you are searching on metatype and not metatype relationship.
{
metatypes{ # specify that we are querying metatypes
Requirement { # name of the metatype being queried for
active
type # these fields map to the Metatype’s properties and
id # match those returned from the introspective query
name
_record { # special object with metadata about the node
id # itself, such as its Deep Lynx id, etc
data_source_id
original_id
import_id
metatype_id
metatype_name
created_at
created_by
modified_at
modified_by
metadata
page # both page and limit are currently under
limit # construction and do not affect the data
}
}
}
}
There are many cases where, instead of simply listing all the instances of a given metatype, the user will want to filter their results to meet certain criteria. Filtering is easily broken down by fields, with the argument as a string as follows:
{
metatypes{
Requirement(name: "M21 - Total Cesium Loading"){
id
name
type
basis
}
}
}
This query would return all requirements with the specified name from DeepLynx, as well as their id, type, and basis.
The string portion of the query actually consists of two parts: a search operator, and the data to search on. As we can see from the query above, the search operator defaults to an implicit "eq". The same query could be rewritten as
{
metatypes{
Requirement(name: "eq M21 - Total Cesium Loading"){
... <fields>
}
}
}
and would return identical results. The search operators are as follows:
Operator | Description | Returns | Example |
---|---|---|---|
eq |
Equals or equal to. This is the implicit behavior. | All nodes with specified fields matching the expression | (name: "eq M21 - Total Cesium Loading") |
neq |
Non-equal or not equal to. | All nodes except those with specified fields matching the expression | (name: "neq M21 - Total Cesium Loading") |
like |
Matches results against a passed-in pattern. Uses wildcard % for any number of characters and _ to match 1 character. Wildcard behavior mimics that of Postgres. |
All nodes whose specified fields match the given pattern | (name: "like %M21%") searches for "M21" anywhere in the name |
in |
Matches one result from an array of options. | All nodes whose specified fields match one option in the array | (id: "in 179,306") |
> , <
|
Check if a numerical field is less than or greater than a certain value. Please note that >= and <= are not currently supported. | All nodes whose specified fields are greater than or less than the given value | (id: "> 200") |
There will likely be situations in which you want to filter on multiple fields within a metatype. This is also possible through GraphQL. To filter on multiple fields, simply separate the fields with whitespace like so:
{
metatypes{
Requirement(
id: "> 200"
name: "like %M21%"
){
id
name
type
basis
}
}
}
This query would return all requirements whose id matches the condition "> 200" and whose name contains the string "M21". This behavior mimics that of an AND conjunction. Support for OR is not currently available.
As was covered in a previous section, each metatype node will contain metadata about the node record as stored in the _record
field:
{
metatypes{
Requirement {
_record { # contains metadata about the node
id # itself, such as its Deep Lynx id, etc
data_source_id
original_id
import_id
metatype_id
metatype_name
created_at
created_by
modified_at
modified_by
metadata
page # both page and limit are currently under
limit # construction and do not affect the data
}
}
}
}
This data will be returned according to what was requested, just like other fields in GraphQL syntax. There are a few sub-fields within this record information which can be queried on. They are: id
, data_source_id
, original_id
, import_id
, page
, and limit
. In the current state, page
and limit
are under construction so querying on them would not be useful. In future updates, these attributes will be used to implement pagination of results.
To query on a sub-property of _record
, the syntax is as follows:
{
metatypes{
Requirement(
_record: {id: "> 200"}
){
_record{
data_source_id
original_id
import_id
}
name
type
}
}
}
The main difference here is that, because _record
is an Object, its sub-properties are queried using an additional set of curly braces ({}
) to specify the sub-field. You can also query for multiple sub-fields just like with a normal query:
{
metatypes{
Requirement(
_record: {id: "> 200" data_source_id: "2"}
){
... <fields>
}
}
}
To query all nodes with a certain relationship to other Metatypes, you can use the _relationship
object in your filter parameters. The syntax is as follows:
metatypes{
<Metatype Name>(
_relationship: {
<relationship name>: {
<Destination Name>: true
}
}
)
}
Any nodes without the specified relationship type will not be returned. For example, given this list of Trigger
nodes:
{
"data": {
"metatypes": {
"Trigger": [
{
"id": "123",
"name": "Asset Trigger"
},
{
"id": "456",
"name": "Non-Asset Trigger"
}
]
}
}
}
Then the following query would return only the asset trigger:
{
metatypes{
Trigger(
_relationship: {
references: {
Asset: true
}
}
){
id
name
}
}
}
==================RESULTS==================
{
"data": {
"metatypes": {
"Trigger": [
{
"id": "123",
"name": "Asset Trigger"
}
]
}
}
}
Upon introspection of a metatype, you can see that there is a _relationship object with its own special type, following the naming convention Metatype_relationshipInfo
. This type contains information about which possible relationships can be included in an edge filter.
...
{
"name": "_relationship",
"type": {
"name": "Trigger_relationshipInfo"
}
},
...
To see the possible relationships, you can perform an introspective query as follows:
__type(name:"Trigger_relationshipInfo"){
name
fields{
name
type{
name
}
}
}
This will return the possible relationships for that metatype:
...
{
"name": "generatedBy",
"type": {
"name": "Trigger_destinationInfo"
}
},
{
"name": "child_of",
"type": {
"name": "Trigger_destinationInfo"
}
},
...
Each Metatype_destinationInfo
object can be further interrogated to see the possible destination metatypes:
__type(name:"Trigger_destinationInfo"){
name
fields{
name
}
}
This will return all possible metatype destinations:
...
{
"name": "Alarm",
"type": {
"name": "String"
}
},
{
"name": "DataItem",
"type": {
"name": "String"
}
},
{
"name": "Asset",
"type": {
"name": "String"
}
},
...
Much like DeepLynx has the ability to query nodes based on Metatype with the metatypes
wrapper, it also now supports the ability to query edges based on Metatype Relationship with the relationships
wrapper. This will not be explained in great detail, since the conventions for this facet of querying are nearly identical to querying on a metatype. For example, to see all edges of the metatype relationship references
, you could execute the following query:
{
relationships{
references{
_record{
id
relationship_name
origin_id
destination_id
}
}
}
}
This would return the edge id, origin, and destination along with the relationship name for only edges of the relationship type references
.
To run an introspective query on _record
information for a relationship, you can look at the edge_recordInfo
type:
{
__type(name:"references"){
fields{
name
type{
name
}
}
}
}
The graph
wrapper allows users to query the graph-like structure of DeepLynx with nodes and edges combined. Each edge has two nodes on either side of it, and these node-edge-node pairs can branch out in complex structures. In order to return this structure and filter through it, there must be a root node and depth specified. From this root node span any number of node-edge-node pairs, and for n
levels of depth, n
hops away from the root will also be returned. As this is a somewhat complex scenario to explain textually, see the diagram below for an example of a root node with id 595
and a depth of 3
:
In order to return the data of this graph-like structure, queries can be executed with the following syntax:
{
graph( # the filters below are required for the graph query
root_node: "595" # the id of the root node
depth: "3" # number of layers deep to recursively search on
){
... fields
}
}
In order to introspectively discover the possible fields for return, you can query on the graph_type
object as follows:
{
__type(name: "graph_type"){
fields{
name
}
}
}
The following unique fields can be queried on for origin, edge and node (put into a query here for convenience):
{
graph( # the filters below are required for the graph query
root_node: "595" # the id of the root node
depth: "3" # number of layers deep to recursively search on
){
# reflect properties of Metatypes/Metatype Relationships
origin_properties
edge_properties
destination_properties
# origin information
origin_id
origin_metatype_id
origin_metatype_name
# edge information
edge_id
relationship_pair_id # Metatype-Relationship-Metatype pair id
relationship_id # Metatype Relationship id
relationship_name # Metatype Relationship name
# destination information
destination_id
destination_metatype_id
destination_metatype_name
# graph metadata
depth # number of layers removed from origin node
path # path of nodes to get to destination id
}
}
This metadata can also be searched on for each (<name>
can contain origin
, destination
or node
)
<name>_data_source
<name>_metadata
<name>_created_by
<name>_created_at
<name>_modified_by
<name>_modified_at
Putting this all together, the following query could be made:
{
graph(
root_node: "595"
depth: "3"
){
depth
origin_id
origin_metatype_name
edge_id
edge_relationship_name
destination_id
destination_metatype_name
}
}
This would return basic information regarding ID and Metatype/Metatype Relationship for each node 3 layers deep in the structure:
{
"data": {
"graph": [
{
"depth": 1,
"origin_id": "595",
"origin_metatype_name": "Material",
"edge_id": "3",
"edge_relationship_name": "inheritance",
"destination_id": "593",
"destination_metatype_name": "Asset"
},
...
{
"depth": 2,
"origin_id": "593",
"origin_metatype_name": "Asset",
"edge_id": "1",
"edge_relationship_name": "references",
"destination_id": "594",
"destination_metatype_name": "Trigger"
},
...
]
}
}
Notice that the sample object with a depth of 2 has its origin_id
as 593, which is the destination_id
of the depth 1 object.
In order to whittle down results to match only a specified Metatype or Metatype Relationship, filters have been provided on Metatype Name/ID and Relationship Name/ID as follows:
{
graph(
root_node: "595"
node_type: { # filter nodes by metatype
name: "Asset" # could use metatype ID instead
}
edge_type: { # filter edges by relationship
id: "777" # could use relationship name instead
}
depth: "3"
){
depth
origin_id
origin_metatype_name
edge_id
edge_relationship_id
edge_relationship_name
destination_id
destination_metatype_name
}
}
This would return only records that contain both an Asset
metatype and the inheritance
relationship:
{
"data": {
"graph": [
{
"depth": 1,
"origin_id": "595",
"origin_metatype_name": "Material",
"edge_id": "3",
"edge_relationship_id": "777",
"edge_relationship_name": "inheritance",
"destination_id": "593",
"destination_metatype_name": "Asset"
},
{
"depth": 2,
"origin_id": "593",
"origin_metatype_name": "Asset",
"edge_id": "4",
"edge_relationship_id": "777",
"edge_relationship_name": "inheritance",
"destination_id": "597",
"destination_metatype_name": "Component"
}
]
}
}
Note that Asset
can be either the origin or the destination. If you want to search for a metatype in only the origin or destination position, simply search for <name>_<property>
where name can be origin
or destination
and property is id
or name
. For example, to search only for relationships where Asset is the destination
(outer node), you could type:
{
graph(
root_node: "595"
node_type: {
destination_name: "Asset" # could also be destination_id
}
edge_type: {
name: "inheritance"
}
depth: "3"
){
depth
origin_id
origin_metatype_name
edge_id
edge_relationship_name
destination_id
destination_metatype_name
}
}
This would return the following object where Asset
is the destination metatype while filtering out any nodes with Asset
as the origin.
{
"data": {
"graph": [
{
"depth": 1,
"origin_id": "595",
"origin_metatype_name": "Material",
"edge_id": "3",
"edge_relationship_name": "inheritance",
"destination_id": "593",
"destination_metatype_name": "Asset"
}
]
}
}
Sections marked with ! are in progress.
- HTTP Authentication Methods
- Generating and Exchanging API Keys for Tokens
- Creating a DeepLynx Enabled OAuth2 App
- Authentication with DeepLynx Enabled OAuth2 App
- Creating an Ontology
- Creating Relationships and Relationship Pairs
- Ontology Versioning
- Ontology Inheritance
- Querying Tabular (Timeseries) Data
- Timeseries Quick Start
- Timeseries Data Source
- Timeseries Data Source via API
- Exporting Data
- Querying Data
- Querying Timeseries Data
- Querying Jazz Data
- Querying Data - Legacy
- Querying Tabular Data