Skip to main content

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.

Templates allow you to structure and organize data stored in CDF and create data models specific to your applications and solutions. By accessing the data through templates, you can scale your solution across more data without changing or redeploying your application.

Each template defines the structure of the data objects that will be using the template. You can, for example, create a template for the pumps you use in your application. In the template, you define that pumps should have inlet pressure as a property referencing a time series. You can use template groups to hold collections of templates.

Each instance of a template is the actual data object. The instance can, for example, be pump_01 with timeseries_240 as the inlet pressure.

Follow the steps below to create a template group and a template to model data, populate the data model with data, and then query the data.

Step 1: Create a template group

Before you can create a template, you need to create a template group using the CDF portal application or an SDK.

Create a template group using the CDF portal application

  1. Navigate to Cognite Data Fusion and select Explore and build > Template management.

  2. Select Create template group and give the group a name and description. The new template group is automatically versioned as v1.

    Create template group
  3. Select Share to give additional users access to edit your template group.

    Share template

Create a template group using an SDK

  1. Install and authenticate the Cognite Python SDK to get started: Getting started with Python SDK. In the below code, assume that client is an authenticated CogniteClient from cognite-sdk.

  2. Create a template group:

    from cognite.client.data_classes import TemplateGroup
    template_group = TemplateGroup(
    "Pump-Dashboard",
    "Template group containing templates for a pump dashboard"
    )
    client.templates.groups.create(template_group)

    Learn more: Using the Python SDK with templates groups.

Step 2: Model data with templates

You can use templates to model the structure of your data objects using the CDF portal application or an SDK.

Model data using the CDF portal application

  1. Navigate to Cognite Data Fusion and select Explore and build > Template management.

  2. Select the template group where you want to create the template.

  3. Select Create template and give the new template a name and description.

  4. Add the fields you want to use in your template:

    • Resource types: Asset, Time series, Files, Sequences.
    • Primitives: String, Int, Float, or Boolean.
    • Relationships: other templates you have defined in your data model.
    Create template UI

    To specify a list, use [nnn]. For example, a list of String is [String].

tip

The template UI form does not display all available features. Use the Code Editor or an SDK to access all features. To use the Code Editor, navigate to Schema tab and select Edit template in the template overview.

Code Editor UI

Once you've made the changes to the code editor on the right side, select Save to save the changes.

Create template

Model data using an SDK

  1. Install and authenticate the Cognite Python SDK to get started: Getting started with Python SDK. In the below code, assume that client is an authenticated CogniteClient from cognite-sdk.

  2. Create a template.

    from cognite.client.data_classes import TemplateGroupVersion

    schema = '''
    "The schema of pumps as seen by the dashboard"
    type Pump @template {
    "Inlet pressure"
    inlet_pressure: TimeSeries,
    "Generation"
    gen: String
    }
    '''
    template_group_version = TemplateGroupVersion(schema)
    client.templates.versions.upsert(template_group.external_id,template_group_version)

Learn more: Data modeling.

Step 3: Populate the data model using templates

When you have created your data modelthe template group and the template to structure the datayou can use the template to populate your model with data.

Populate the data model using the CDF portal application

  1. Navigate to Cognite Data Fusion and select Explore and build > Template management.

  2. Select the template group and the template that you want use to populate your data model.

  3. Add an instance to your template from the list of available assets. Then populate the rest of the fields.

  4. Select + to add a time series, and the select the time series.

    Populate template
important

The template user interface does not display all available features. You can use the Code Editor or an SDK to access all features.

Learn more: Data ingestion.

Suggestions

When you add instances and properties to your template, the suggestion algorithm learns your patterns, metadata, and the connections between the time series and infers the time series for the other instances.

Suggestions

You can find suggested entries in an overview, or for each property.

Bulk suggestions

Review, approve, or reject the suggestions in the Suggestions overview panel.

Populate the data model using an SDK

  1. Install and authenticate the Cognite Python SDK to get started: Getting started with Python SDK. In the below code, assume that client is an authenticated CogniteClient from cognite-sdk.

  2. Create a pump instance using the template you created in the previous example.

    from cognite.client.data_classes import TemplateGroup, TemplateGroupVersion, TemplateInstance, ConstantResolver

    pump_1 = TemplateInstance(
    external_id="asset_1",
    template_name="Pump",
    field_resolvers={
    "inlet_pressure": ConstantResolver("timeseries_inletpressure_240"),
    "gen": ConstantResolver("Hex")
    }
    )
    pump_2 = TemplateInstance(
    external_id="asset_2",
    template_name="Pump",
    field_resolvers={
    "inlet_pressure": ConstantResolver("timeseries_inletpressure_249"),
    "gen": ConstantResolver("hex")
    }
    )

    template_group_list = client.templates.versions.list("Pump-Dashboard")
    latest_version = template_group_list[0].version
    client.templates.instances.upsert("Pump-Dashboard", latest_version, [pump_1, pump_2])

Learn more: Data ingestion.

Suggestions

To interact with Templates suggestions via Python, install the Python Experimental SDK.

Alpha

The Python Experimental SDK is an alpha version of the Cognite Python SDK.

pip install cognite-sdk-experimental

Learn more in the experimental SDK documentation.

Step 4: Query data with templates

When you have populated the data model with templates, you can query the data using the CDF portal application, an SDK, a URL, or with the Cognite Data Source for Grafana.

Query data using the CDF portal application

  1. Navigate to Cognite Data Fusion and select Explore and build > Template management.

  2. Select the template group and the template that you want to use to query data.

  3. Use the Query explorer tab to create GraphQL queries.

    Query explorer
    tip

    Use CMD/CTRL + SPACE to toggle autocomplete.

Query data using an SDK

  1. Install and authenticate the Cognite Python SDK to get started: Getting started with Python SDK. In the below code, assume that client is an authenticated CogniteClient from cognite-sdk.

  2. Create and run a query.

    query = '''
    {
    pumpQuery {
    items {
    _externalId
    inlet_pressure {
    externalId
    datapoints(limit: 100) {
    timestamp
    value
    }
    }
    }
    }
    }
    '''
    result = client.templates.graphql_query("Pump-Dashboard", 1, query)

Learn more: Data querying.

Query data via a URL

With the correct authentication headers you can make queries directly against the data model via the GraphQL endpoint:

https://{cluster}.cognitedata.com/api/v1/projects/{project}/templategroups/{externalId}/versions/{version}/graphql

Where:

  • {cluster} is the name of the CDF cluster (api, greenfield, etc.)
  • {project} is the name of the CDF project.
  • {externalId} is the external id of the template group to query (for example, Pump-Dashboard)
  • {version} is the version of the template group to query (for example, 2).

You can also use GraphQL or Postman (with the correct authentication headers) to run the queries.

Query data via the Cognite Data Source for Grafana

You can use a modified version of the Cognite Data Source for Grafana with added support for templates to query data. Learn more about the Cognite Data Source for Grafana.

If you already have Grafana on your computer:

  1. Download this zip file.
  2. Extract the file into your local Grafana plugins folder.
  3. Restart Grafana.

Install

Run Grafana with the data source installed using Docker:

  1. docker run -p 3000:3000 --name grafana -e "GF_INSTALL_PLUGINS=https://github.com/cognitedata/templates-docs/raw/master/assets/cognitedata-datasource.zip;cognitedata-templates-datasource" grafana/grafana

  2. You should now have access to Grafana at http://localhost:3000.

    Note: The default username/password for signing in is admin/admin.

Getting started

To use the Cognite Data Source for Grafana:

  1. In Grafana, navigate to Configuration, select Data Sources, then Add data source, and choose Cognite Data Fusion (w/ Templates).

  2. Give the data source a name, provide the name of the project, and the credentials.

  3. Click Save & test.

  4. Create a dashboard with a panel, and choose the CDF Templates datasource you just created.

  5. Navigate to the Template Query tab and select your template group in the dropdown.

    Create template group