Tables API ·

Use the Tables API to manage tables and their data. See Create a table by API for more details and examples.

You can accomplish the following tasks with the Tables API:

All URIs are relative to https://api.imply.io/v1

Create a table

URL

POST /tables

Parameters

Request body

type: TableRequest required
A table to be created

Responses

A successful request returns an HTTP 2XX status code and a JSON response body of type Table.

201 SUCCESS

400 ERROR

409 ERROR

415 ERROR

Created.

The request succeeded, and data was returned in the response body.

Invalid table.

The server received a bad request. This may occur if the specified table has a missing or malformed field. For example:

A dimension or measure in rollupSchema refers to a nonexistent column from inputSchema.
A column is listed in both the dimensions and measures lists.

Example body:

{
    "code": 400,
    "message": "Unable to process JSON"
}

Table already exists.

An existing table with the same name already exists within the same account. See the Location response header for the URL of the conflicting table object.

Example body:

{
    "error": {
        "code": "AlreadyExists",
        "message": "A table with name [Example Table] already exists",
        "target": "Example Table",
        "innererror": {
            "code": "TableAlreadyExists",
            "message": "A table with name [Example Table] already exists",
            "name": "Example Table",
            "existingTableId": "43442169-2c54-4957-8c3b-500b5ad698b1"
        }
    }
}

Unsupported media type.

Example body:

{
    "code": 415,
    "message": "HTTP 415 Unsupported Media Type"
}

Sample request

curl --location --request POST 'https://api.imply.io/v1/tables' \
--header 'Authorization: Bearer <Bearer Token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Example Table",
    "inputSchema": [
        {
            "name": "channel",
            "type": "string"
        },
        {
            "name": "cityName",
            "type": "string"
        }
    ]
}'

Sample response

{
    "name": "Example Table",
    "id": "43442169-2c54-4957-8c3b-500b5ad698b1",
    "totalDataSize": 0,
    "totalRows": 0,
    "lastUpdateDateTime": "2021-12-02T01:41:56.080115754Z",
    "status": "no_data",
    "createdBy": "cb73ff39-3212-44d4-820e-c302fd456f55",
    "lastModifiedBy": "cb73ff39-3212-44d4-820e-c302fd456f55",
    "inputSchema": [
        {
            "type": "string",
            "name": "channel"
        },
        {
            "type": "string",
            "name": "cityName"
        }
    ],
    "segmentTimeResolution": "day"
}

Delete a table

This operation cancels all scheduled and in-progress ingestion jobs.

URL

DELETE /tables/{tableId}

Parameters

Path parameters

tableId type: UUID required
The server-generated ID of the table to delete

Responses

202 SUCCESS

404 ERROR

Accepted.

A 202 response code signifies that the request was successfully received; however, the resource may not be fully deleted as this process is a long running process.

Check the status of a table by checking the table's metadata. When the status field holds no_data, the delete data operation is complete.

Table not found.

Example body:

{
    "error": {
        "code": "NotFound",
        "message": "Table with id [65b362a2-fc8b-4211-82a5-9f9d4ce237a5] not found"
    }
}

Sample request

curl --location --request DELETE 'https://api.imply.io/v1/tables/65b362a2-fc8b-4211-82a5-9f9d4ce237a5' \
--header 'Authorization: Bearer <Bearer Token>'

Delete the data stored in a table

This operation cancels all scheduled and in-progress ingestion jobs.

URL

DELETE /tables/{tableId}/data

Parameters

Path parameters

tableId type: UUID required
The server-generated ID of the table whose data should be deleted

Responses

202 SUCCESS

404 ERROR

Accepted.

A 202 response code signifies that the request was successfully received; however, the resource may not be fully deleted as this process is a long running process.

Check the status of a table by checking the table's metadata. When the status field holds no_data, the delete data operation is complete.

Table not found.

Example body:

{
    "error": {
        "code": "NotFound",
        "message": "Table with id [724578f8-4ded-4f69-9213-ea5480b26800] not found"
    }
}

Sample request

curl --location --request DELETE 'https://api.imply.io/v1/tables/724578f8-4ded-4f69-9213-ea5480b268e3/data' \
--header 'Authorization: Bearer <Bearer Token>'

Delete the data stored in a table within a specific interval

This operation cancels all scheduled and in-progress ingestion jobs.

URL

DELETE /tables/{tableId}/data/interval

Parameters

Path parameters

tableId type: UUID required
The server-generated ID of the table

Request body

type: JSON object required
A JSON object with the following format:
- Key: interval
- Value: A string ISO 8601 interval that defines the time range within which to delete data. For example, 2012-01-01T00:00:00.00Z/2012-01-03T00:00:00.00Z.

Responses

A successful request returns an HTTP 2XX status code and a JSON object with the following format:

Key: jobId
Value: ID of the ingestion job

202 SUCCESS

400 ERROR

404 ERROR

Accepted.

Bad request. This may result if the requested interval is not aligned by day granularity.

Table not found.

Example body:

{
    "error": {
        "code": "NotFound",
        "message": "Table with id [724578f8-4ded-4f69-9213-ea5480b26800] not found"
    }
}

Sample request

curl --location --request DELETE 'https://api.imply.io/v1/tables/724578f8-4ded-4f69-9213-ea5480b268e3/data/interval' \
--header 'Authorization: Bearer <Bearer Token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "interval": "2019-08-20T00:00:00.00Z/2019-08-20T12:00:00.00Z"
}'

Sample response

{
  "jobId" : "046b6c7f-0b8a-43b9-b35d-6489e6daee91"
}

Get a table's metadata

URL

GET /tables/{tableId}

Parameters

Path parameters

tableId type: UUID required
The server-generated ID of the table for which to get the metadata

Query parameters

detail type: String
The detail of the table to return (default: summary)
- detailed - Includes number of rows, storage bytes, and status of table.
- summary - Does not include number of rows, storage bytes, nor status of table.

Responses

A successful request returns an HTTP 2XX status code and a JSON response body of type Table.

200 SUCCESS

404 ERROR

OK.

The request succeeded, and data was returned in response body.

Table not found.

Example body:

{
    "error": {
        "code": "NotFound",
        "message": "Table with id [65b362a2-fc8b-4211-82a5-9f9d4ce237a5] not found"
    }
}

Sample request

curl --location --request GET 'https://api.imply.io/v1/tables/45f85cda-cad3-410c-bebb-afe30deef823' \
--header 'Authorization: Bearer <Bearer Token>'

Sample response

{
    "name": "Koalas to the Max",
    "id": "45f85cda-cad3-410c-bebb-afe30deef823",
    "lastUpdateDateTime": "2021-09-29T23:31:45Z",
    "createdBy": "dbb63d7c-3b35-4268-b351-17e0a98a7bfb",
    "lastModifiedBy": "dbb63d7c-3b35-4268-b351-17e0a98a7bfb",
    "inputSchema": [
        {
            "type": "string",
            "name": "continent"
        },
        {
            "type": "string",
            "name": "country"
        },
        {
            "type": "string",
            "name": "city"
        },
        {
            "type": "string",
            "name": "session"
        },
        {
            "type": "string",
            "name": "timezone"
        },
        {
            "type": "long",
            "name": "session_length"
        }
    ],
    "segmentTimeResolution": "day"
}

List available tables

URL

GET /tables

Parameters

Query parameters

detail type: String
The detail of the table to return (default: summary)
- detailed - Includes number of rows, storage bytes, and status of table.
- summary - Does not include number of rows, storage bytes, nor status of table.

name type: String
The name of the table to query for

Responses

A successful request returns an HTTP 2XX status code and a JSON object with the following format:

Key: values
Value: An array of JSON objects for each available table. Each object is described by TableSummary.

200 SUCCESS

OK.

The request succeeded, and data was returned in the response body.

Sample request

curl --location --request GET 'https://api.imply.io/v1/tables' \
--header 'Authorization: Bearer <Bearer Token>'

Sample response

{
    "values": [
        {
            "name": "Koalas",
            "id": "3b5195d9-0160-4ab7-9cf4-d82be8a59130",
            "version": 3,
            "totalDataSize": 0,
            "totalRows": 0,
            "lastUpdateDateTime": "2022-02-25T00:22:52Z",
            "createdByUsername": "service-account-roles-test",
            "status": "no_data",
            "timePartitioning": "day"
        },
        {
            "name": "Store Sales",
            "id": "0b280f42-f3b2-4ade-af87-d7a93f5abec7",
            "version": 0,
            "totalDataSize": 126967762,
            "totalRows": 500000,
            "lastUpdateDateTime": "2021-11-22T22:15:42Z",
            "status": "available",
            "timePartitioning": "day"
        }
    ]
}

Update a table

URL

PUT /tables/{tableId}

Parameters

Path parameters

tableId type: UUID required
The server-generated ID of the table to update

Request body

type: TableRequest required
The table to be updated

Responses

A successful request returns an HTTP 2XX status code and a JSON response body of type Table.

200 SUCCESS

400 ERROR

404 ERROR

409 ERROR

415 ERROR

OK.

The request succeeded, and data was returned in response body.

Invalid table.

The server received a bad request. This may occur if the specified table has a missing or malformed field. For example:

A dimension or measure in rollupSchema refers to a nonexistent column from inputSchema.
A column is listed in both the dimensions and measures lists.

Example body:

{
    "code": 400,
    "message": "Unable to process JSON"
}

Table not found.

Example body:

{
    "error": {
        "code": "NotFound",
        "message": "Table with id [65b362a2-fc8b-4211-82a5-9f9d4ce237a5] not found"
    }
}

Conflict.

Example body:

{
    "code": 409,
    "message": "Table already exists named Koalas to the Max. "
}

Unsupported media type.

Example body:

{
    "code": 415,
    "message": "HTTP 415 Unsupported Media Type"
}

Sample request

curl --location --request PUT 'https://api.imply.io/v1/tables/43442169-2c54-4957-8c3b-500b5ad698b1' \
--header 'Authorization: Bearer <Bearer Token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Example Table",
    "inputSchema": [
        {
            "name": "country",
            "type": "string"
        },
        {
            "name": "cityName",
            "type": "string"
        }
    ]
}'

Sample response

{
    "name": "Example Table",
    "id": "43442169-2c54-4957-8c3b-500b5ad698b1",
    "totalDataSize": 0,
    "totalRows": 0,
    "lastUpdateDateTime": "2021-12-02T22:39:10.811882058Z",
    "status": "no_data",
    "createdBy": "cb73ff39-3212-44d4-820e-c302fd456f55",
    "lastModifiedBy": "cb73ff39-3212-44d4-820e-c302fd456f55",
    "inputSchema": [
        {
            "type": "string",
            "name": "country"
        },
        {
            "type": "string",
            "name": "cityName"
        }
    ],
    "segmentTimeResolution": "day"
}