Skip to main content

Ingest data with templates

Early adopter

Templates is currently in beta testing and only available to customers via our Early Adopter program. For more information and to request to join the program, visit the Flexible data modeling group on the Cognite Hub.

For each type you can declare 3 types of properties: Primitives, CDF resources, and Relationships. Additionally, each of of the properties can be a list. To learn more about data modelling, see Model data with templates.

Ingesting or populating data for templates is a way to declare the value for each field of an new instance, as identified by an externalId. Declaring a value for a field is called resolving a field for a field resolver. Each field of an instance is bound to a field resolver.

This section outlines the different ways to ingest data with field resolvers.

Ingesting from / asUISDK
PrimitivesString✅ via ConstantResolver
Long✅ via ConstantResolver
Int✅ via ConstantResolver
Float✅ via ConstantResolver
Boolean✅ via ConstantResolver
CDF resourcesAsset✅ via ConstantResolver
Time series✅ via ConstantResolver
Synthetic time series✅ via SyntheticTimeSeriesResolver
Sequence✅ via ConstantResolver
File✅ via ConstantResolver
Event
RAW✅ via RawResolver
Lists✅ via ConstantResolver
Relationships✅ via ConstantResolver

ConstantResolver

Use the ConstantResolver to resolve a field to a value that is only persisted in the template group itself.

Resolve to a primitive

type MyType @template {
myStringField: String
myIntField: Int
myFloatField: Float
myBooleanField: Boolean
child: NonTemplateType
}

type NonTemplateType { # Non template type
textField: String
}
TemplateInstance(
external_id="id-for-instance",
template_name="MyType",
field_resolvers={
"myStringField": ConstantResolver(value="Foo") # String
"myIntField": ConstantResolver(value=1) # Long, Int
"myFloatField": ConstantResolver(value=1.1) # Float
"myBooleanField": ConstantResolver(value=True) # Boolean
"child": ConstantResolver(value={"textField": "hello world"}) # Object
},
)

Resolve to a CDF resource

type MyType @template {
myAssetField: Asset
myTimeSeriesField: TimeSeries
myFileField: File
mySequenceField: Sequence
}
instance = TemplateInstance(
external_id="id-for-instance",
template_name="MyType",
field_resolvers={
"myAssetField": ConstantResolver(value="asset-external-id") # Asset's External ID
"myTimeSeriesField": ConstantResolver(value="ts-external-id") # Time Series' External ID
"myFileField": ConstantResolver(value="file-external-id") # File's External ID
"mySequenceField": ConstantResolver(value="sequence-external-id") # Sequence's External ID
},
)

Resolve to relationships

Built-in types and templates can relate to each other. You can define the relationship between templates by specifying the externalId of the relating instances.

type Well @template {
name: String
}
type System @template {
sub_well: Well # References the type above
}
# Well instance
well_instance = TemplateInstance(
external_id="myWell",
template_name="Well",
field_resolvers={
"name": ConstantResolver(value="Favorite Well") # String field for Well's name
},
)
# System instance referencing Well
system_instance = TemplateInstance(
external_id="mySystem",
template_name="MyType",
field_resolvers={
"sub_well": ConstantResolver(value="myWell") # Referencing the well via external_id
},
)

Resolve to lists of primitives and relationships

For relationships, the externalIds can originate from any field resolver which resolves to a string or an array of strings, depending if it's a one-to-one or a one-to-many relationship.

type Well @template {
name: String
}
type MyType @template {
tags: [String]
myAssetFields: [Asset]
wells: [Well]
}
# Well instance
well_instance = TemplateInstance(
external_id="myWell",
template_name="Well",
field_resolvers={
"name": ConstantResolver(value="Favorite Well") # String field for Well's name
},
)
instance = TemplateInstance(
external_id="id-for-instance",
template_name="MyType",
field_resolvers={
"tags": ConstantResolver(value=["foo", "bar"]) # Strings in an array
"myAssetFields": ConstantResolver(value=["asset-external-id"]) # Asset's External IDs, in an array
"wells": ConstantResolver(value=["myWell"]) # Wells' externalIds, in an array
},
)

Learn more:

SyntheticTimeSeriesResolver

Use the SyntheticTimeSeriesResolver to resolve a field of type TimeSeries to a synthetic time series in CDF. The only required argument is the synthetic time series expression, but you can also set the description, the unit, and if it's a step series or a string series.

type MyType @template {
myTimeSeriesField: SyntheticTimeSeries
}
instance = TemplateInstance(
external_id="id-for-instance",
template_name="MyType",
field_resolvers={
"myTimeSeriesField": SyntheticTimeSeriesResolver(
expression="sin(pow(TS{externalId='Norway_confirmed'}, 2))",
description="Weird sin time series",
is_step=False,
is_string=False,
unit="radians",
) # Synthetic time series definition
},
)

Learn more:

RawResolver

Use the RawResolver to resolve a field to a value from a specific row and column in RAW.

There is no data model field that is of the type RAW. It simply resolves to the table -> row -> column's value as a value.

type MyType @template {
someValue: String
}
instance = TemplateInstance(
external_id="id-for-instance",
template_name="MyType",
field_resolvers={
"someValue": RawResolver(
db_name="SomeDb",
table_name="SomeTable",
row_key="someRow",
column_name="someColumn"
) # RAW resolver definition
},
)

Learn more:

Complete example

type System @template {
name: String!
tags: [String]!
wells: [Well]
parentSystem: System
}
type Well @template {
pressureSensor: SyntheticTimeSeries
assets: [Asset]
sourceName: String
weight: Float
}
TemplateInstance(
external_id="system1",
template_name="System",
field_resolvers={
"name": RawResolver(
db_name="SomeDb",
table_name="SomeTable",
row_key="someRow",
column_name="someColumn"
) # RAW resolver definition
"tags": ConstantResolver(value=["foo", "bar"]),
"wells": ConstantResolver(value=["well1"]),
},
)
TemplateInstance(
external_id="system2",
template_name="System",
field_resolvers={
"name": ConstantResolver(value="name"),
"tags": ConstantResolver(value=["foo", "bar", "star"]),
"wells": ConstantResolver(value=["well2"]),
"parentSystem": ConstantResolver(value="system1"),
},
)
TemplateInstance(
external_id="well1",
template_name="Well",
field_resolvers={
"pressureSensor": SyntheticTimeSeriesResolver(
expression="sin(pow(TS{externalId='Norway_confirmed'}, 2))",
description="Weird sin time series",
is_step=False,
is_string=False,
unit="radians",
) # Synthetic time series definition,
"assets": ConstantResolver(value=["someAssetExtId", "someOtherAssetExtId"]),
"sourceName": ConstantResolver(value="someString"),
"weight": ConstantResolver(value=12.3),
},
)
TemplateInstance(
external_id="well2",
template_name="Well",
field_resolvers={
"assets": ConstantResolver(value=["someAssetExtId", "someOtherAssetExtId"]),
"sourceName": ConstantResolver(value="someString"),
"weight": ConstantResolver(value=12.3),
},
)

SDK documentation