Series cache service#

The Series Cache service manages internal chunks of data cached by Nominal’s backend.

OpenAPI file: SeriesCacheService.json

Endpoints#

Get chunks#

POST /timeseries/series-cache/v1/logical-series/{logicalSeriesRid}/get-chunks

Fetches “chunks” of series that are stored as Arrow files in S3. This endpoint is being deprecated for new series in favor of batchGetCachedSeries

Path parameters

logicalSeriesRid string (RID) required

​

Body

startTimestamp Timestamp required

​

Fields of Timestamp
seconds integer (int64) required

​

nanos integer (int64) required

​

endTimestamp Timestamp required

​

resolutionNanos integer (int64) required

​

Response

chunks array of Chunk

​

Fields of Chunk
rid string (RID)

​

type ChunkType

​

Values of ChunkType
ARROW_WITH_RELATIVE_TIMESTAMPS

​

ARROW_WITH_ABSOLUTE_TIMESTAMPS

​

logicalSeriesRid string (RID)

​

startTimestamp Timestamp

​

Fields of Timestamp
seconds integer (int64)

​

nanos integer (int64)

​

endTimestamp Timestamp

​

count integer (int64)

The number of distinct timestamps contained within the chunk.

sizeInBytes integer (int64)

​

resolution integer (int64)

​

handle Handle

​

Set type to "s3".

s3 S3Handle

​

Fields of S3Handle
s3Path string

​

Request

curl -X POST "https://api.gov.nominal.io/api/timeseries/series-cache/v1/logical-series/<logical series rid>/get-chunks" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "startTimestamp": {
    "seconds": 1,
    "nanos": 1
  },
  "endTimestamp": {
    "seconds": 1,
    "nanos": 1
  },
  "resolutionNanos": 1
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/timeseries/series-cache/v1/logical-series/<logical series rid>/get-chunks",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "startTimestamp": {"seconds": 1, "nanos": 1},
        "endTimestamp": {"seconds": 1, "nanos": 1},
        "resolutionNanos": 1,
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/timeseries/series-cache/v1/logical-series/<logical series rid>/get-chunks",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "startTimestamp": {"seconds": 1, "nanos": 1},
        "endTimestamp": {"seconds": 1, "nanos": 1},
        "resolutionNanos": 1,
    },
)
response.raise_for_status()
print(response.json())

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/series-cache/v1/logical-series/<logical series rid>/get-chunks",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "startTimestamp": {"seconds": 1, "nanos": 1},
                "endTimestamp": {"seconds": 1, "nanos": 1},
                "resolutionNanos": 1,
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "chunks": [
    {
      "rid": "<chunk rid>",
      "type": "ARROW_WITH_RELATIVE_TIMESTAMPS",
      "logicalSeriesRid": "<logical series rid>",
      "startTimestamp": {
        "seconds": 1,
        "nanos": 1
      },
      "endTimestamp": {
        "seconds": 1,
        "nanos": 1
      },
      "count": 1,
      "sizeInBytes": 1,
      "resolution": 1,
      "handle": {
        "type": "s3",
        "s3": {
          "s3Path": "<s3 path>"
        }
      }
    }
  ]
}

Create chunks#

POST /timeseries/series-cache/v1/logical-series/{logicalSeriesRid}/create-chunks

Deprecated: Deprecated in favor of batchCreateChunks

Path parameters

logicalSeriesRid string (RID) required

​

Body

createChunks array of CreateChunk

​

Fields of CreateChunk
type ChunkType required

​

Values of ChunkType
ARROW_WITH_RELATIVE_TIMESTAMPS

​

ARROW_WITH_ABSOLUTE_TIMESTAMPS

​

logicalSeriesRid string (RID) required

​

startTimestamp Timestamp required

​

Fields of Timestamp
seconds integer (int64) required

​

nanos integer (int64) required

​

endTimestamp Timestamp required

​

count integer (int64) required

​

sizeInBytes integer (int64) required

​

resolution integer (int64) required

​

handle Handle required

​

Set type to "s3".

s3 S3Handle

​

Fields of S3Handle
s3Path string required

​

Response

chunkRids array of string (RID)

​

Request

curl -X POST "https://api.gov.nominal.io/api/timeseries/series-cache/v1/logical-series/<logical series rid>/create-chunks" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "createChunks": [
    {
      "type": "ARROW_WITH_RELATIVE_TIMESTAMPS",
      "logicalSeriesRid": "<logical series rid>",
      "startTimestamp": {
        "seconds": 1,
        "nanos": 1
      },
      "endTimestamp": {
        "seconds": 1,
        "nanos": 1
      },
      "count": 1,
      "sizeInBytes": 1,
      "resolution": 1,
      "handle": {
        "type": "s3",
        "s3": {
          "s3Path": "<s3 path>"
        }
      }
    }
  ]
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/timeseries/series-cache/v1/logical-series/<logical series rid>/create-chunks",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "createChunks": [
            {
                "type": "ARROW_WITH_RELATIVE_TIMESTAMPS",
                "logicalSeriesRid": "<logical series rid>",
                "startTimestamp": {"seconds": 1, "nanos": 1},
                "endTimestamp": {"seconds": 1, "nanos": 1},
                "count": 1,
                "sizeInBytes": 1,
                "resolution": 1,
                "handle": {"type": "s3", "s3": {"s3Path": "<s3 path>"}},
            },
        ],
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/timeseries/series-cache/v1/logical-series/<logical series rid>/create-chunks",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "createChunks": [
            {
                "type": "ARROW_WITH_RELATIVE_TIMESTAMPS",
                "logicalSeriesRid": "<logical series rid>",
                "startTimestamp": {"seconds": 1, "nanos": 1},
                "endTimestamp": {"seconds": 1, "nanos": 1},
                "count": 1,
                "sizeInBytes": 1,
                "resolution": 1,
                "handle": {"type": "s3", "s3": {"s3Path": "<s3 path>"}},
            },
        ],
    },
)
response.raise_for_status()
print(response.json())

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/series-cache/v1/logical-series/<logical series rid>/create-chunks",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "createChunks": [
                    {
                        "type": "ARROW_WITH_RELATIVE_TIMESTAMPS",
                        "logicalSeriesRid": "<logical series rid>",
                        "startTimestamp": {"seconds": 1, "nanos": 1},
                        "endTimestamp": {"seconds": 1, "nanos": 1},
                        "count": 1,
                        "sizeInBytes": 1,
                        "resolution": 1,
                        "handle": {"type": "s3", "s3": {"s3Path": "<s3 path>"}},
                    },
                ],
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "chunkRids": [
    "<chunk rid>"
  ]
}

Batch create chunks#

POST /timeseries/series-cache/v1/batch-create-chunks

Body

createChunks array of CreateChunk

​

Fields of CreateChunk
type ChunkType required

​

Values of ChunkType
ARROW_WITH_RELATIVE_TIMESTAMPS

​

ARROW_WITH_ABSOLUTE_TIMESTAMPS

​

logicalSeriesRid string (RID) required

​

startTimestamp Timestamp required

​

Fields of Timestamp
seconds integer (int64) required

​

nanos integer (int64) required

​

endTimestamp Timestamp required

​

count integer (int64) required

​

sizeInBytes integer (int64) required

​

resolution integer (int64) required

​

handle Handle required

​

Set type to "s3".

s3 S3Handle

​

Fields of S3Handle
s3Path string required

​

Response

chunkRids array of string (RID)

​

Request

curl -X POST "https://api.gov.nominal.io/api/timeseries/series-cache/v1/batch-create-chunks" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "createChunks": [
    {
      "type": "ARROW_WITH_RELATIVE_TIMESTAMPS",
      "logicalSeriesRid": "<logical series rid>",
      "startTimestamp": {
        "seconds": 1,
        "nanos": 1
      },
      "endTimestamp": {
        "seconds": 1,
        "nanos": 1
      },
      "count": 1,
      "sizeInBytes": 1,
      "resolution": 1,
      "handle": {
        "type": "s3",
        "s3": {
          "s3Path": "<s3 path>"
        }
      }
    }
  ]
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/timeseries/series-cache/v1/batch-create-chunks",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "createChunks": [
            {
                "type": "ARROW_WITH_RELATIVE_TIMESTAMPS",
                "logicalSeriesRid": "<logical series rid>",
                "startTimestamp": {"seconds": 1, "nanos": 1},
                "endTimestamp": {"seconds": 1, "nanos": 1},
                "count": 1,
                "sizeInBytes": 1,
                "resolution": 1,
                "handle": {"type": "s3", "s3": {"s3Path": "<s3 path>"}},
            },
        ],
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/timeseries/series-cache/v1/batch-create-chunks",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "createChunks": [
            {
                "type": "ARROW_WITH_RELATIVE_TIMESTAMPS",
                "logicalSeriesRid": "<logical series rid>",
                "startTimestamp": {"seconds": 1, "nanos": 1},
                "endTimestamp": {"seconds": 1, "nanos": 1},
                "count": 1,
                "sizeInBytes": 1,
                "resolution": 1,
                "handle": {"type": "s3", "s3": {"s3Path": "<s3 path>"}},
            },
        ],
    },
)
response.raise_for_status()
print(response.json())

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/series-cache/v1/batch-create-chunks",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "createChunks": [
                    {
                        "type": "ARROW_WITH_RELATIVE_TIMESTAMPS",
                        "logicalSeriesRid": "<logical series rid>",
                        "startTimestamp": {"seconds": 1, "nanos": 1},
                        "endTimestamp": {"seconds": 1, "nanos": 1},
                        "count": 1,
                        "sizeInBytes": 1,
                        "resolution": 1,
                        "handle": {"type": "s3", "s3": {"s3Path": "<s3 path>"}},
                    },
                ],
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "chunkRids": [
    "<chunk rid>"
  ]
}

Delete chunks#

POST /timeseries/series-cache/v1/logical-series/{logicalSeriesRid}/delete-chunks

Deletes the chunks that intersect the given time range. Does not delete the corresponding files from S3.

Path parameters

logicalSeriesRid string (RID) required

​

Body

startTimestamp Timestamp required

​

Fields of Timestamp
seconds integer (int64) required

​

nanos integer (int64) required

​

endTimestamp Timestamp required

​

Response

deletedChunkRids array of string (RID)

​

Request

curl -X POST "https://api.gov.nominal.io/api/timeseries/series-cache/v1/logical-series/<logical series rid>/delete-chunks" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "startTimestamp": {
    "seconds": 1,
    "nanos": 1
  },
  "endTimestamp": {
    "seconds": 1,
    "nanos": 1
  }
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/timeseries/series-cache/v1/logical-series/<logical series rid>/delete-chunks",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "startTimestamp": {"seconds": 1, "nanos": 1},
        "endTimestamp": {"seconds": 1, "nanos": 1},
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/timeseries/series-cache/v1/logical-series/<logical series rid>/delete-chunks",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "startTimestamp": {"seconds": 1, "nanos": 1},
        "endTimestamp": {"seconds": 1, "nanos": 1},
    },
)
response.raise_for_status()
print(response.json())

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/series-cache/v1/logical-series/<logical series rid>/delete-chunks",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "startTimestamp": {"seconds": 1, "nanos": 1},
                "endTimestamp": {"seconds": 1, "nanos": 1},
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "deletedChunkRids": [
    "<chunk rid>"
  ]
}

Errors#

Errors shows how these errors are sent.

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

Status

Name

Notes

409

ChunkAlreadyExists

Types#

Chunk#

rid string (RID) required

​

type ChunkType required

​

logicalSeriesRid string (RID) required

​

startTimestamp Timestamp required

​

endTimestamp Timestamp required

​

count integer (int64) required

The number of distinct timestamps contained within the chunk.

sizeInBytes integer (int64) required

​

resolution integer (int64) required

​

handle Handle required

​

ChunkType#

ARROW_WITH_RELATIVE_TIMESTAMPS

​

ARROW_WITH_ABSOLUTE_TIMESTAMPS

​

CreateChunk#

type ChunkType required

​

logicalSeriesRid string (RID) required

​

startTimestamp Timestamp required

​

endTimestamp Timestamp required

​

count integer (int64) required

​

sizeInBytes integer (int64) required

​

resolution integer (int64) required

​

handle Handle required

​

Handle#

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

s3 S3Handle

​

S3Handle#

s3Path string required

​

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

​

Page design based on Scalar, MIT License.