Open Data Model Queries
Queries follow the GraphQL specifications (GraphQL.org, GraphQL.com) with the following restrictions:
- No support of GraphQL arguments, the filtering being performed by filter directives
- No support of GraphQL variables
If you intent to put comments in your query, please have a look at the recommended way to do it.
Basic queries
The purpose of queries is to return nodes defined in the schema and to project node properties defined in the schema.
Consider the following schema:
type ParentNode {
Key: String
Children : [ChildNode] @direct_relation(Type: "PARENT_OF" Age:Int)
}
type ChildNode {
Key: String
Name: String
}
type Query {
ParentNodes : [ParentNode]
ChildNodes : [ChildNode]
}
A query is a string in the form:
query optional_name { query_name { projections } }
query is the query keyword. It must be lower-case in order to fullfill GrapQL requirements
optional_name is the optional name of the query, it is not used by the Opend Data Model engine
query_name is the name of one of the queries declared in the schema (in this example, ParentNodes or ChildNodes)
projections is a list (comma-separated or space-separated) of properties that the Open Data Model must return in the query result. When a projected property is a object type (other than scalar), this property must also contain projections.
Here are some examples based on the above schema:
query { ParentNodes { Key } }
query { ParentNodes { Key Children { Key}} }
query { ParentNodes { Key Children { Key Name}} }
query { ParentNodes { Key,Children { Key, Name}} }
query { ChildNodes { Key Name} }
Filter directive
You can apply a fiter on queries to restrict the number of output results. The filter is expressed by a ***@where*** directive using the following syntax:
@where( Node: filter_expression, Relation: filter_expression)
***@where*** is the filter keyword. It is valid on query name and on object type properties only, not on scalar types
Node indicates that the filter expression should target node properties. It is optional if only Relation filter should apply. Relation indicates that the filter expression should target relation properties. It is optional if only Node filter should apply. filter_expression is the filter expression that filters the nodes and/or relations.
Warning
The Data Hub internal types support filtering on Id and Name only.
Examples:
query {
ParentNodes @where(Node: \"Key STARTS WITH 'test'\") {
Key
}
}
Returns the Key property of all nodes of type ParentNode having the Key property starting with 'test'. . If ParentNode match the where condition, the ParentNodes output will be an empty array.
query {
ParentNodes {
Key
Children @where (Node : "Name = 'John'") {
Key
Name
}
}
}
Returns the Key and Name properties of all nodes of type ChildNode having the Name property equal to 'John'. If no Children of a node ParentNode match the where condition, the Children output will be an empty array.
query {
ParentNodes {
Key
Children @where (Node: "Name = 'John'" Relation: "Age > 10") {
Key
Name
}
}
}
Returns the Key property of all nodes of type ParentNode along with the Key and Name properties of all nodes of type ChildNode having the Name property equal to 'John'. If no Children of a node ParentNode match the where condition, the Children output will be an empty array.
query {
ParentNodes @where(Node: \"Key STARTS WITH 'test'\") {
Key
Children @where (Node: "Name = 'John'" Relation: "Age > 10") {
Key
Name
}
}
}
Returns the Key property of all nodes of type ParentNode having the Key property starting with 'test' along with the Key and Name properties of all nodes of type ChildNode having the Name property equal to 'John' and linked to it's parent by a relation of type PARENT_OF having a property Age > 10. If no Children of a node ParentNode match the where condition, the Children output will be an empty array.
Query result
The query result is a JSON file containing node instances and projected properties.
A query such as query { ParentNodes { Key Children { Key Name}} } whould produce a result
{
"data": {
"ParentNodes": [
{
"Key": "pkey1",
"Children": [
{
"Key": "ckey1",
"Name": "cname1"
},
{
"Key": "ckey2",
"Name": "cname2"
}
]
},
{
"Key": "pkey2",
"Children": [
{
"Key": "ckey3",
"Name": "cname3"
}
]
}
]
}
}
Query result limits
The Open Data Model will produce an error if a query returns more than 10k nodes. To manage this limitation, you should divide such a query into sub-queries that return less than 10k nodes by applying filters such as:
query { NodeWithId @where (Node : "Id >= 0 AND Id < 10000 ") { ... }
query { NodeWithId @where (Node : "Id >= 10000 AND Id < 20000 ") { ... }
...
Discard null properties
It could happen that some properties will be null in the JSON output. This could lead to a lot of "noise" in the output document. If you want the Opend Data Model engine to remove null properties from the output, add the directive discard_null to the query type
Imagine that a query query { ParentNodes { Key Children { Name}} } produces the following output:
{
"data": {
"ParentNodes": [
{
"Key": "pkey1",
"Children": null
},
{
"Key": "pkey2",
"Children": null
}
]
}
}
By adding the directve discard_null to the query, i.e. query @discard_null { ParentNodes { Key Children { Name}} }, the output will become:
{
"data": {
"ParentNodes": [
{
- "Key": "pkey1"
},
{
"Key": "pkey2"
}
]
}
}
All the null properties have been removed from th output document.
Authentication
The Open Data Model is available via the Data Hub REST API which requires authentication. All Data Hub recources returned by a query is subject to user restrictions
User restrictions
DataHubSite, DataHubSource and DataHubVariables are subkect to user restrictions, meaning that the result set will be limited to the entities the interactive user (the one who is logged in) has access to.
Imagine the following schema:
type MySources {
Sources : [DataHubSource] @direct_relation(Type: "HAS_ACCESS")
}
type Query {
AllSources : [MySources]
}
If the intercative user has retricted access to source Ids [1,2], the query query { AllSources { DataHubSources @where (Node : "Id IN [1,2,3,4]") {Id}}} will return the following result:
{
"data": {
"AllSources": [
{
"DataHubSource": [
{
"Id": "1"
},
{
"Id": "2"
}
]
}
]
}
}
Source Ids [3,4] are not returned by the query since the user does not have access to them.
If the interactive user has a Manager role, the same query will produce the following result:
{
"data": {
"AllSources": [
{
"DataHubSource": [
{
"Id": "1"
},
{
"Id": "2"
},
{
"Id": "3"
},
{
"Id": "4"
}
]
}
]
}
}
All requested sources are returned since a Manager is has access to all sources.