Series metadata service#

[INTERNAL] Series metadata represents the constant information about data in a series - specifically, the name, units, a description, and the tags. Series metadata can be used to query points from specific series depending on the tag value selections.

OpenAPI file: SeriesMetadataService.json

Endpoints#

Change data type#

POST /timeseries/archetype/v1/series-archetype/change-data-type

This endpoint lets an authorized workspace caller change how one nominal dataset channel is interpreted. This updates metadata and future series resolution. It does not rewrite historical point rows.

Body

dataSourceRid string (RID) required

Identifies the data source whose channel metadata should be changed.

channel string required

Identifies the channel name within the data source.

expectedCurrentType NominalDataType required

Provides the exact nominal type the caller expects to be stored in the locator before the change.

Values of NominalDataType

DOUBLE
STRING
LOG
INT64
UINT64
DOUBLE_ARRAY
STRING_ARRAY
STRUCT
VIDEO
SPATIAL

newType NominalDataType required

Provides the exact nominal type future series resolution should use.

Response

seriesMetadataRid string (RID)

Identifies the series metadata row being changed.

oldType NominalDataType

Reports the exact nominal type read from the existing locator.

Values of NominalDataType

DOUBLE
STRING
LOG
INT64
UINT64
DOUBLE_ARRAY
STRING_ARRAY
STRUCT
VIDEO
SPATIAL

newType NominalDataType

Reports the exact nominal type requested by the caller.

Request

curl

curl -X POST "https://api.gov.nominal.io/api/timeseries/archetype/v1/series-archetype/change-data-type" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "dataSourceRid": "<data source rid>",
  "channel": "<channel>",
  "expectedCurrentType": "DOUBLE",
  "newType": "DOUBLE"
}'

requests

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/timeseries/archetype/v1/series-archetype/change-data-type",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "dataSourceRid": "<data source rid>",
        "channel": "<channel>",
        "expectedCurrentType": "DOUBLE",
        "newType": "DOUBLE",
    },
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/timeseries/archetype/v1/series-archetype/change-data-type",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "dataSourceRid": "<data source rid>",
        "channel": "<channel>",
        "expectedCurrentType": "DOUBLE",
        "newType": "DOUBLE",
    },
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/timeseries/archetype/v1/series-archetype/change-data-type",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "dataSourceRid": "<data source rid>",
                "channel": "<channel>",
                "expectedCurrentType": "DOUBLE",
                "newType": "DOUBLE",
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "seriesMetadataRid": "<series metadata rid>",
  "oldType": "DOUBLE",
  "newType": "DOUBLE"
}

Batch create video series#

POST /timeseries/archetype/v1/series-archetype/video-channel

Batch creates series metadata for video channels if they don’t exist. Idempotent - returns existing SeriesMetadataRid if already exists.

Body

requests array of CreateVideoSeriesRequest

Fields of CreateVideoSeriesRequest

datasetRid string (RID) required

channel string required

tags map of TagName to string

timeBounds TimeBounds required

Fields of TimeBounds

start Timestamp required

Fields of Timestamp

seconds integer (int64) required
nanos integer (int64) required

end Timestamp required

Response

responses array of CreateVideoSeriesResponse

Fields of CreateVideoSeriesResponse

seriesMetadataRid string (RID)
seriesUuid string (UUID)

Request

curl

curl -X POST "https://api.gov.nominal.io/api/timeseries/archetype/v1/series-archetype/video-channel" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "requests": [
    {
      "datasetRid": "<dataset rid>",
      "channel": "<channel>",
      "timeBounds": {
        "start": {
          "seconds": 1,
          "nanos": 1
        },
        "end": {
          "seconds": 1,
          "nanos": 1
        }
      }
    }
  ]
}'

requests

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/timeseries/archetype/v1/series-archetype/video-channel",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "requests": [
            {
                "datasetRid": "<dataset rid>",
                "channel": "<channel>",
                "timeBounds": {
                    "start": {"seconds": 1, "nanos": 1},
                    "end": {"seconds": 1, "nanos": 1},
                },
            },
        ],
    },
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/timeseries/archetype/v1/series-archetype/video-channel",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "requests": [
            {
                "datasetRid": "<dataset rid>",
                "channel": "<channel>",
                "timeBounds": {
                    "start": {"seconds": 1, "nanos": 1},
                    "end": {"seconds": 1, "nanos": 1},
                },
            },
        ],
    },
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/timeseries/archetype/v1/series-archetype/video-channel",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "requests": [
                    {
                        "datasetRid": "<dataset rid>",
                        "channel": "<channel>",
                        "timeBounds": {
                            "start": {"seconds": 1, "nanos": 1},
                            "end": {"seconds": 1, "nanos": 1},
                        },
                    },
                ],
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "responses": [
    {
      "seriesMetadataRid": "<series metadata rid>",
      "seriesUuid": "<series uuid>"
    }
  ]
}

Errors#

Errors shows how these errors are sent.

Each error’s errorName is SeriesMetadata: followed by its name below.

Status	Name	Notes
400	`DataSourcesNotFound`
400	`IncompatibleSeriesMetadataUpdate`
400	`InvalidDataSource`
404	`SeriesMetadataNotFound`	The error supports both series metadata lookup shapes. RID-based lookups populate `rid`; channel lookups populate `dataSourceRid` and `channel`.

Types#

BigQueryLocatorTemplate#

valueColumn string required
timeColumn string required
type BigQueryType required

BigQueryType#

DOUBLE
STRING

ChannelKind#

Classifies how a channel is used. COMMAND channels accept commands through the Command Service.

STANDARD
COMMAND

CreateSeriesMetadataRequest#

channel string required: This name should be unique amongst SeriesMetadata within the data source. All series created from this metadata will share this name.
dataSourceRid string (RID) required
locator LocatorTemplate required
unit string
description string
channelKind ChannelKind: Classifies how the channel is used. Omitted values default to STANDARD.
tags map of TagName to string deprecated: Tags specified here will take precedence over tags specified in the RunDatasource, in the case that both specify the same TagName. Deprecated: Deprecated. Should not be used.

CreateVideoSeriesRequest#

Creates series and metadata for a video channel if it doesn’t exist. Returns the SeriesMetadataRid of the created or existing series metadata.

datasetRid string (RID) required
channel string required
tags map of TagName to string
timeBounds TimeBounds required

CreateVideoSeriesResponse#

seriesMetadataRid string (RID) required
seriesUuid string (UUID) required

Empty#

An empty JSON object, {}.

Influx1LocatorTemplate#

database string required
measurement string required
field string required
type InfluxType required

Influx2LocatorTemplate#

bucket string required
measurement string required
valueColumn string: If omitted, defaults to _value. Can be used to extract tag values.
field string required
type InfluxType required

InfluxType#

BOOLEAN
NUMERIC
STRING

LocatorTemplate#

Set type to the name of one of the other fields, and set only that field.

timescaleDb TimescaleDbLocatorTemplate
influx Influx2LocatorTemplate
influx1 Influx1LocatorTemplate
nominal NominalLocatorTemplate
timestream TimestreamLocatorTemplate
visualCrossing VisualCrossingLocatorTemplate
bigQuery BigQueryLocatorTemplate
video VideoLocatorTemplate
spatial SpatialLocatorTemplate

NominalDataType#

The data types supported by Nominal’s database.

DOUBLE
STRING
LOG
INT64
UINT64
DOUBLE_ARRAY
STRING_ARRAY
STRUCT
VIDEO
SPATIAL

NominalLocatorTemplate#

channel string required
type NominalDataType required

SeriesDataType#

The data types that are available for querying.

DOUBLE
STRING
LOG
INT
UINT
DOUBLE_ARRAY
STRING_ARRAY
STRUCT
VIDEO
SPATIAL

SeriesMetadata#

rid string (RID) required
channel string required
dataSourceRid string (RID) required
locator LocatorTemplate required
unit string
description string
tags map of TagName to string deprecated: Tags specified here will take precedence over tags specified in the RunDatasource, in the case that both specify the same TagName. Deprecated: Deprecated. Should not be used.
seriesDataType SeriesDataType
channelKind ChannelKind: Classifies how the channel is used. Omitted values should be treated as STANDARD.

SpatialLocatorTemplate#

channel string required

TimeBounds#

Time bounds for the video file. Used to update the series time bounds

start Timestamp required
end Timestamp required

TimescaleDbLocatorTemplate#

table string required
schema string required
column string required
timeColumn string required
type TimescaleType required

TimescaleType#

BOOLEAN
DOUBLE
STRING

Timestamp#

Deprecated for new APIs. Use google.protobuf.Timestamp for absolute instants in proto APIs.

This legacy nanosecond precision timestamp type is represented by an epoch time in seconds and a nanosecond offset. The nanosecond offset is from the start of the epoch second, so must be less than 1 billion.

seconds integer (int64) required
nanos integer (int64) required

TimestreamLocatorTemplate#

table string required
measure string required
attribute string
type TimestreamType required

TimestreamType#

DOUBLE
STRING

UnitUpdate#

UnitUpdate is used to either set a unit, or to clear an existing unit.