# Series cache service

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

OpenAPI file: [`SeriesCacheService.json`](https://dev.nominal.io/api/_downloads/10a859cbaad6ea1f7409ab721741bbab/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`](https://dev.nominal.io/api/rest/series-cache-service.md#timestamp) required
:   ​

    Fields of `Timestamp`

    `seconds` integer (int64) required
    :   ​

    `nanos` integer (int64) required
    :   ​

`endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/series-cache-service.md#timestamp) required
:   ​

`resolutionNanos` integer (int64) required
:   ​

Response

`chunks` array of [`Chunk`](https://dev.nominal.io/api/rest/series-cache-service.md#chunk)
:   ​

    Fields of `Chunk`

    `rid` string (RID)
    :   ​

    `type` [`ChunkType`](https://dev.nominal.io/api/rest/series-cache-service.md#chunktype)
    :   ​

        Values of `ChunkType`

        `ARROW_WITH_RELATIVE_TIMESTAMPS`
        :   ​

        `ARROW_WITH_ABSOLUTE_TIMESTAMPS`
        :   ​

    `logicalSeriesRid` string (RID)
    :   ​

    `startTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/series-cache-service.md#timestamp)
    :   ​

        Fields of `Timestamp`

        `seconds` integer (int64)
        :   ​

        `nanos` integer (int64)
        :   ​

    `endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/series-cache-service.md#timestamp)
    :   ​

    `count` integer (int64)
    :   The number of distinct timestamps contained within the chunk.

    `sizeInBytes` integer (int64)
    :   ​

    `resolution` integer (int64)
    :   ​

    `handle` [`Handle`](https://dev.nominal.io/api/rest/series-cache-service.md#handle)
    :   ​

        **s3**

        Set `type` to `"s3"`.

        `s3` [`S3Handle`](https://dev.nominal.io/api/rest/series-cache-service.md#s3handle)
        :   ​

            Fields of `S3Handle`

            `s3Path` string
            :   ​

Request

**curl**

```shell
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
}'
```

**requests**

```python
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())
```

**httpx**

```python
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())
```

**aiohttp**

```python
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`

```json
{
  "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`](https://dev.nominal.io/api/rest/series-cache-service.md#createchunk)
:   ​

    Fields of `CreateChunk`

    `type` [`ChunkType`](https://dev.nominal.io/api/rest/series-cache-service.md#chunktype) required
    :   ​

        Values of `ChunkType`

        `ARROW_WITH_RELATIVE_TIMESTAMPS`
        :   ​

        `ARROW_WITH_ABSOLUTE_TIMESTAMPS`
        :   ​

    `logicalSeriesRid` string (RID) required
    :   ​

    `startTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/series-cache-service.md#timestamp) required
    :   ​

        Fields of `Timestamp`

        `seconds` integer (int64) required
        :   ​

        `nanos` integer (int64) required
        :   ​

    `endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/series-cache-service.md#timestamp) required
    :   ​

    `count` integer (int64) required
    :   ​

    `sizeInBytes` integer (int64) required
    :   ​

    `resolution` integer (int64) required
    :   ​

    `handle` [`Handle`](https://dev.nominal.io/api/rest/series-cache-service.md#handle) required
    :   ​

        **s3**

        Set `type` to `"s3"`.

        `s3` [`S3Handle`](https://dev.nominal.io/api/rest/series-cache-service.md#s3handle)
        :   ​

            Fields of `S3Handle`

            `s3Path` string required
            :   ​

Response

`chunkRids` array of string (RID)
:   ​

Request

**curl**

```shell
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>"
        }
      }
    }
  ]
}'
```

**requests**

```python
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())
```

**httpx**

```python
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())
```

**aiohttp**

```python
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`

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

### Batch create chunks

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

Body

`createChunks` array of [`CreateChunk`](https://dev.nominal.io/api/rest/series-cache-service.md#createchunk)
:   ​

    Fields of `CreateChunk`

    `type` [`ChunkType`](https://dev.nominal.io/api/rest/series-cache-service.md#chunktype) required
    :   ​

        Values of `ChunkType`

        `ARROW_WITH_RELATIVE_TIMESTAMPS`
        :   ​

        `ARROW_WITH_ABSOLUTE_TIMESTAMPS`
        :   ​

    `logicalSeriesRid` string (RID) required
    :   ​

    `startTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/series-cache-service.md#timestamp) required
    :   ​

        Fields of `Timestamp`

        `seconds` integer (int64) required
        :   ​

        `nanos` integer (int64) required
        :   ​

    `endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/series-cache-service.md#timestamp) required
    :   ​

    `count` integer (int64) required
    :   ​

    `sizeInBytes` integer (int64) required
    :   ​

    `resolution` integer (int64) required
    :   ​

    `handle` [`Handle`](https://dev.nominal.io/api/rest/series-cache-service.md#handle) required
    :   ​

        **s3**

        Set `type` to `"s3"`.

        `s3` [`S3Handle`](https://dev.nominal.io/api/rest/series-cache-service.md#s3handle)
        :   ​

            Fields of `S3Handle`

            `s3Path` string required
            :   ​

Response

`chunkRids` array of string (RID)
:   ​

Request

**curl**

```shell
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>"
        }
      }
    }
  ]
}'
```

**requests**

```python
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())
```

**httpx**

```python
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())
```

**aiohttp**

```python
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`

```json
{
  "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`](https://dev.nominal.io/api/rest/series-cache-service.md#timestamp) required
:   ​

    Fields of `Timestamp`

    `seconds` integer (int64) required
    :   ​

    `nanos` integer (int64) required
    :   ​

`endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/series-cache-service.md#timestamp) required
:   ​

Response

`deletedChunkRids` array of string (RID)
:   ​

Request

**curl**

```shell
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
  }
}'
```

**requests**

```python
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())
```

**httpx**

```python
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())
```

**aiohttp**

```python
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`

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

## Errors

[Errors](https://dev.nominal.io/api/legacy.md#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`](https://dev.nominal.io/api/rest/series-cache-service.md#chunktype) required
:   ​

`logicalSeriesRid` string (RID) required
:   ​

`startTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/series-cache-service.md#timestamp) required
:   ​

`endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/series-cache-service.md#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`](https://dev.nominal.io/api/rest/series-cache-service.md#handle) required
:   ​

### ChunkType

`ARROW_WITH_RELATIVE_TIMESTAMPS`
:   ​

`ARROW_WITH_ABSOLUTE_TIMESTAMPS`
:   ​

### CreateChunk

`type` [`ChunkType`](https://dev.nominal.io/api/rest/series-cache-service.md#chunktype) required
:   ​

`logicalSeriesRid` string (RID) required
:   ​

`startTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/series-cache-service.md#timestamp) required
:   ​

`endTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/series-cache-service.md#timestamp) required
:   ​

`count` integer (int64) required
:   ​

`sizeInBytes` integer (int64) required
:   ​

`resolution` integer (int64) required
:   ​

`handle` [`Handle`](https://dev.nominal.io/api/rest/series-cache-service.md#handle) required
:   ​

### Handle

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

`s3` [`S3Handle`](https://dev.nominal.io/api/rest/series-cache-service.md#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](https://scalar.com), MIT License.