Loading...
Loading...
Loading...
Loading...
Loading...
GraphQL queries are composed of:
Queries
Arguments
Fields
Each Class in TerminusDB automatically generates a top-level Query. Each property of the class automatically generates both arguments and fields.
The names of the types of arguments and fields are generated automatically subject to name mapping.
In turn, each property which is an edge leading to a new object of a class will have its own field with arguments.
Each concrete data query will be terminal and will generate a specific field parameter for search.
For example, using the following TerminusDB schema:
TerminusDB will generate the following GraphQL class.
The Person
query, allows you to query for a person at the top level, along with a number of arguments, including: a filter
(for search), a limit
for reducing to a defined length of results, an offset
, for obtaining results starting from some offset (for use in paging) and an orderBy
to obtain the results in a defined order.
In addition, we have the various fields of a Person
object, each of which may have arguments if they are objects or simple data types for terminal fields.
One can use such a query by using the GraphQL endpoint.
Arguments are restrictions or meta-fields about the query. These can be used to limit results, or filter to specific results, as well as perform ordering.
id
The id of an object can be directly supplied, in order to ensure that we only obtain the specific object of interest.
A person might be retrieved by supplying the id as a variable in the following way:
offset
GraphQL will retrieve all objects in the database for a given class type, unless offset
and limit
are supplied. offset
will start a query from a given result offset, allowing the query user to page results.
This query retrieves the second page of a 3-object page of persons.
limit
GraphQL will retrieve all objects in the database for a given class type, unless offset
and limit
are supplied. limit
will only find the limit-number of results, allowing the query user to page results.
This query retrieves the second page of a 3-object page of persons.
orderBy
The orderBy filter allows the user to order results according to some data in the object. For instance, to create an ordering on people, we might write:
This will yield Persons from youngest to oldest, ordering by name in the event of a "tie" on date of birth.
filter
Filters allow you to restrict to specific results by reducing the set to those objects which match the filter fields.
Each filter is an input object, defined for the specific class and generated automatically by TerminusDB. The Person
object defined above gets the input objects:
Filters can apply to immediate values, such as the dob
(date of birth), which can be restricted using a time comparison, or they can be filters on linked objects, such as the Person_Collection_Filter
which allows us to compare with our friends.
In GraphQL we might write a simple query over people as:
This finds name and date of birth of all people who have a name which contains "Joe" or "Joesph" and who are friends with someone named "Jim" or "James", in order of ascending name.
Filters have to work with all of the GraphQL base types, along with the extensions which TerminusDB currently supports (DateTime
, and BigInt
).
Big integers use the widely available BigInt
type extension to GraphQL.
The Filters available for BigInt are:
eq
: Equality
ne
: disequality
lt
: Less than
le
: Less than or equal
gt
: Greater than
ge
: Greater than or equal
When a field of an object refers to a BigInt
, we can filter it by writing a query along the following lines:
Date time objects use the widely available DateTime
type extension to GraphQL.
The Filters available for BigInt are:
eq
: Equality
ne
: disequality
lt
: Less than
le
: Less than or equal
gt
: Greater than
ge
: Greater than or equal
Strings are native GraphQL types. TerminusDB exposes the following filter options for strings:
eq
: Equality
ne
: Disequality
lt
: Less than
le
: Less than or equal
gt
: Greater than
ge
: Greater than or equal
regex
: Matches regex
startsWith
: Matches the string prefix
allOfTerms
: Contains all terms in the list of terms
anyOfTerms
: Contains any of the terms in the list of terms
A query filter using strings could be written as follows:
Booleans are native GraphQL types. TerminusDB exposes the following filter options:
eq
: Equality
ne
: Disequality
A query filter using booleans could be written as follows:
Integers (signed, 32-bit integers) are native GraphQL types. TerminusDB exposes the following filter options:
eq
: Equality
ne
: disequality
lt
: Less than
le
: Less than or equal
gt
: Greater than
ge
: Greater than or equal
A query filter using booleans could be written as follows:
_and
The _and
filter combinator allows us to chain constraints. It takes two filter objects relevant at the current level.
We can find all civilizations of a high Kardashev scale using a query such as:
_or
The _or
filter combinator allows us to make choices of constraints. It takes two filter objects relevant at the current level. It is implicitly combined as if with _and
, with any filters at the current level.
We can find all civilizations of a high Kardashev scale, which is also a galactic civilisation using a query such as:
_not
The _not
operator allows us to combine other constraints with dis-constraints, which remove any elements which match its sub-filter.
We can ask for galactic civilizations which have not mastered energy acquisition at level 3 on the Kardashev scale.
Each TerminusDB class has associated with it, some number of fields. These fields include each field that is defined in the class.
For instance, given the TerminusDB class:
We have a query field for each of name
, dob
and friend
. However we also have the following specially defined fields:
_id
This returns the fully qualified URI of the given instance of the Person
class being returned.
_type
This returns the class at which this instance is instantiated. This is useful when a super-class is queried, as we can obtain what concrete subclass it corresponds to.
_PROPERTY_of_CLASS
The backlink is a way to find all instances that point to a given class. The backlink is generated automatically for every edge which terminates at the current class.
For example, with the Person class:
We automatically get the backlink _friend_of_Person
that says which people view us as their friends.
For instance, we can construct the following query:
This will find the name of every person who views the top level Person
us as their friend (i.e. has a friend
link to the current person).
_path_to_CLASS
A path query allows us to use regular graph expressions to follow links from the current object to another object of CLASS
.
Using the Person
example:
We can find everyone within 2-degrees of separation with the following path query:
See the complete syntax for path queries for more details on the semantics of the path argument.
TerminusDB has its own flexible schema language which is designed to be compatible with RDF. The RDF world identifies resources with IRIs which are flexible, and use a relatively large space of available characters.
GraphQL, by contrast, has a very restrictive allowed character set for naming. Essentially only Alphanumeric characters using un-accented Latin. That is, it is essentially restricted to [A-Z][a-z][0-9][_]
.
Because of this, we have some naming conventions to translate automatically from TerminusDB classes and properties to GraphQL named classes and properties. While we have endevoured to do so in a way that is unlikely to create naming collisions, these are never-the-less possible.
TerminusDB generates GraphQL schema automatically as a mapping from TerminusDB. TerminusDB's definition language is a strict super-set of GraphQL and so is able to faithfully represent GraphQL features.
For each class in TerminusDB, there is a range of classes that are defined automatically by TerminusDB in the associated GraphQL schema.
When names are likely to create conflicts with user-defined names, TerminusDB will typically use an _
at the beginning to avoid naming conflicts. This is done on filter fields that share the same object level with user-defined properties for instance: _and
, _or
and _not
.
All names of GraphQL classes in TerminusDB and all properties of TerminusDB classes, as well as all enums, are translated to viable GraphQL names. This is done by replacing each non-representable character with an _
. In addition, underscores at the beginning of a class name or property are disallowed. This is to ensure there are no collisions with TerminusDB's own auto-generated properties and classes.
Should a collision arise, TerminusDB should give a GraphQL error on retrieval of the schema. In future, we will allow this check to occur at schema submission time, and will also allow explicit renaming in TerminusDB classes.
For instance, the TerminusDB class is defined as:
will be translated to:
TerminusDB also exposes its internal working graphs, the system graph, the meta graph, and the commit-graph. These three graphs can be queried with a self-documenting GraphQL interface by going to the appropriate API for a data product.
For instance, to get only system graph access, you can use the following endpoint:
To get the System Graph and Meta graph which belongs to a specific data product you can use the following endpoint:
To get access to branches, commits, commit logs, as well as the meta and system graph, you can use the following endpoint:
A reference guide to get you up and running with TerminusDB & TerminusCMS using GraphQL and Apollo Client
Install dependencies
Initialize ApolloClient and Connect with TerminusDB
Import the required dependencies needed -
Or
Initialize ApolloClient by passing its constructor with a configuration object with the TerminusDB server endpoint, user credentials and cache fields.
Extra information about the Apollo client cache can be found on their website
You will need to get your API key to connect with terminusCMS
TerminusDB hosts a GraphQL endpoint at:
For instance, with a data product named admin/people
, and a locally installed TerminusDB, you can query it at:
For TerminusCMS you can use the following URL:
Where ORG
is your organization, and DATA_PRODUCT
is the name of your data product.
Since TerminusDB requires authentication to access data products, you will need to use the authentication method that has been configured for your server.
Using Basic Auth, the default method in locally installed TerminusDBs, you can supply the Authorization header, with your basic auth. (To generate a Basic Auth string, see Basic Auth Generator).
For example, if you would like to connect to admin/people
with the apollo client to download the associated GraphQL schema, simply use:
In TerminusCMS you can use an API key with the following header.
For instance, with the Apollo client, you can download your schema as follows:
Where my_token_file
contains an API token for TerminusCMS.
See how to connect with the Apollo Client.
TerminusDB ships with a GraphiQL graphical GraphQL query interface and schema browser. This is a quick way to get acquainted with GraphQL in TerminusDB.
You can reach this browser at:
You will also need to set your Authorization header in the Header dialog box at the bottom center.
For instance, in the default install, as: