Skip to main content

Specifications for data modeling and querying

Beta

The features described in this section are currently in beta testing and are subject to change. We recommend that you don't use the features in production systems.

For more information, request to join the data modeling group on the Cognite Hub.

This article describes the specifications for data modeling and data querying.

Data modeling specifications

The data model format is GraphQL Schema Definition Language. Each data model has many types, consisting of properties with a specified type.

Types, properties and more types

Each type contains properties that reference another type, forming a relationship. You can also specify the fields as an array (list) of another type.

Use ! to indicate that a field is required and that each instance of the template must contain the value.

To add comments, enter "..." above the field/type definition.

Limits

A data model may consist of at most 100 types, each having at most 100 properties. A data model can contain up to 10 million instances (nodes and edges).

Example data model

This example is a simple data model for movies.

type Movie {
"name of the movie"
name: String!
actors: [Actor]
watchedIt: Boolean
}
type Actor {
name: String!
age: Int
}

Where:

  • Movie type has the properties name and watchedIt properties.
    • name must be a String type, and must exist on all instances of Movie.
    • watchedIt must be a Boolean type.
  • Movie type has an actors relationship to a list of Actors.
  • Actor has the properties name and age,
    • name must be a String type, and must exist on all instances of Actor.
    • age must be an Int type.
  • Movie.name has a comment/description (name of the movie).

Categories of types

The following types are available:

  • Primitives - simple types like String, Int, Int64, Float, Boolean, JSONObject, TimeSeries, and Timestamp.
  • User defined - any other types that' are defined in the data model. In the example above, Actor and Movie are examples of user defined types, forming relationships between types.

All of these types can exist in a list (for example [String]) or in singular form (for example String) through [...].

TypeSupportedDescription
PrimitivesString
IntRepresents integers that can be stored in a 32-bit integer.
Int64Represents integers that can be stored in a 64-bit integer.
JSONObjectRepresents an opaque JSON object or null.
TimestampRepresents a timestamp with UTC-offset, formatted as a ISO-8601 date time string, with potentially microsecond resolution. As input, the timestamp can be formatted as a number, which is assumed to represent milliseconds since Unix epoch.
Float
Boolean
Primitives (CDF resources)AssetYou can model this directly via a custom data model type.
TimeSeriesModeling capabilities for TimeSeries is on the roadmap
SyntheticTimeSeries
GeospacialModeling capabilities for Geospatial is on the roadmap
3DModeling capabilities for 3D is on the roadmap
Sequence
FileModeling capabilities for Files is coming soon
EventYou can model this directly via a custom data model type.
User Defined TypeAny type the user defines .Creates a relationship that users need to ingest seperately.
Lists([XXX])
Required (!)
InterfaceSupport for Interface is on the roadmap
UnionSupport for Union is on the roadmap

Versioning

Every template group is versioned, and the version changes when the data model is updated with a breaking change. Since you can query each version individually, consumers are not directly affected by breaking changes.

Also, each version has its own set of template instances. The data is tied to each version of a template group, and there is no automatic migration between versions.

Data querying specifications

You can query the template instances with GraphQL. A query has these key sections:

  • A query intent (query MyQueryName {, or just { as a shorthand.

  • The query to run. For templates, this is one of 3 types of query (with an optional alias, for example myAlias: listActor):

    • list<type>, for example listActor lists based on filter parameters.

    • search<type>, for example searchActor searches based on a query parameter.

    • aggregate<type>, for example aggregateActor aggregates (count, average etc.) based on a field.

      See below for more details.

  • The query parameters. For example filter: {...} or limit: 1000.

  • The properties to return at a specified depth.

GraphQL example

query myQuery {
countryQuery {
items {
name
demographics {
populationSize
growthRate
}
deaths {
datapoints(limit: 100) {
timestamp
value
}
}
}
nextCursor
}
demographicsQuery(
filter: {
_and: [{ populationSize: { gte: 2 } }, { populationSize: { lte: 10 } }]
}
) {
items {
populationSize
growthRate
metadata {
key
value
}
}
}
}

Where:

  • myQuery - declares the query intent.
  • countryQuery and demographicsQuery - are the queries to run.
  • The parameters are Country:100 for the death time series data points, and the Demographics: filter of populationSize between 2 and 10.
  • The properties to return, for Country: items -> name, demographic -> populationSize, growthRate, etc.

For more information, see the GraphQL documentation.

Query types

list queries

list<type> enables you to filter and sort data quickly. For list<type> you can use these properties and parameters:

  • Properties

    • items - Specify which properties to be returned.
    • pageInfo - Details about the current set of items that is returned, such as hasPreviousPage and hasNextPage if there is a startCursor or endCursor,.
  • Parameters

    • filter - The filter you want to provide. This is based on the properties in your data model and you can do array of and, or and not to make more complex queries.
    • sort - The sorting you want to provide. To specify an array of properties and if they are sorted in ASC or DESC order.
    • after - The nextCursor from the previous query.
    • first - The maximum number of items to return. To fetch more items, use a anew query using the endCursor parameter (Default: 1000).

search queries

search<type> enables you to search and query data quickly. For search<type> you can use these properties and parameters:

  • Properties - The same as for the list queries.

  • Parameters

    • filter - The filter you want to provide. This is based on the properties in your data model and you can do array of and, or, and not to make more complex queries.
    • properties - The properties you want to search on. This can be an array of properties.
    • query - The actual search queries. Wildcards are supported.
    • first - The maximum number of items to return. To fetch more items, use a anew query using the endCursor parameter (Default: 1000)

aggregate queries

aggregate<type> enables you to aggregate data quickly. For aggregate<type> you can use these properties and parameters:

  • Properties

    • group - Depending on the groupBy parameter, this indicates the group.
    • avg - For number properties, you can ask for the average.
    • count - For any type of properties, you can ask for the total count.
    • histogram(interval: <number>) - For number properties, you can ask for the histogram at the given interval.
    • max - For number properties, you can ask for the maximum value.
    • min - For number properties, you can ask for the minimum value.
    • sum - For number properties, you can ask for the total sum.
    • pageInfo - The details about the current set of items that is returned, such as hasPreviousPage and hasNextPage to allong if there is a startCursor or endCursor.
  • Parameters

    • filter - The filter you want to provide. This is based on the properties in your data model and you can do array of and, or, and not to make more complex queries.
    • properties - The properties you want to search. This can be an array of properties.
    • query - The actual search queries. Wildcards are supported.
    • groupBy - The field to group by (no relationship allowed),
    • after - The nextCursor from the previous query.

Filter specifications

FieldFilterHow to use
Top level filtersAnyand{and: [{...},{...}]} = if everything is true.
or{or: [{...},{...}]} = if at least one is true.
not{not: {...}} = if false.
PrimitivesAnyeq{eq: ...}
in{in: ["..."]} = if any of term.
NullableisNull{isNull: True} = if the field is empty.
Stringprefix{prefix: "..."} = starts with.
Int/Int64/Float/Timestamplt{lt: ...} = less than.
gt{gt: ...} = greater than.
lte{lte: ...} = less than or equals.
gte{gte: ...} = greater than or equals.
TimeSeriesNone supported.
User Defined TypeNone supported.
Lists([XXX])None supported.