API docs by Redocly

Timeplus (v1)

Download OpenAPI specification:Download

API Support: support@timeplus.com URL: https://timeplus.com

Welcome to the Timeplus HTTP REST API specification.

Alerts v1beta2

list alerts

Get all alerts.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an alert

Create an alert. Please refer to the documentation of alert for more details.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create alert request parameters

action
required
string

Sink template - the following properties are used to create the sink One action can be map to a sink

description
string
name
required
string
object

Detailed properties to create the sink

resolve_sql
string
severity
required
integer
trigger_sql
required
string

Persistent query template - the following properties are used to create the persistent query

Responses

Request samples

Content type
application/json
{
  • "action": "string",
  • "description": "string",
  • "name": "string",
  • "properties": {
    },
  • "resolve_sql": "string",
  • "severity": 0,
  • "trigger_sql": "string"
}

Response samples

Content type
application/json
{
  • "action": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "string",
  • "id": "string",
  • "instance": {
    },
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "string",
  • "properties": {
    },
  • "resolve_query": {
    },
  • "resolve_sql": "string",
  • "severity": 0,
  • "status": "running",
  • "trigger_query": {
    },
  • "trigger_sql": "string"
}

delete an alert

Delete the alert with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

alert ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get an alert

Get an alert with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

alert ID

Responses

Response samples

Content type
application/json
{
  • "action": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "string",
  • "id": "string",
  • "instance": {
    },
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "string",
  • "properties": {
    },
  • "resolve_query": {
    },
  • "resolve_sql": "string",
  • "severity": 0,
  • "status": "running",
  • "trigger_query": {
    },
  • "trigger_sql": "string"
}

update an alert

Update the specific alert with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

alert ID

Request Body schema: application/json
required

update alert request parameters

action
required
string

Sink template - the following properties are used to create the sink One action can be map to a sink

description
string
name
required
string
object

Detailed properties to create the sink

resolve_sql
string
severity
required
integer
trigger_sql
required
string

Persistent query template - the following properties are used to create the persistent query

Responses

Request samples

Content type
application/json
{
  • "action": "string",
  • "description": "string",
  • "name": "string",
  • "properties": {
    },
  • "resolve_sql": "string",
  • "severity": 0,
  • "trigger_sql": "string"
}

Response samples

Content type
application/json
{
  • "action": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "string",
  • "id": "string",
  • "instance": {
    },
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "string",
  • "properties": {
    },
  • "resolve_query": {
    },
  • "resolve_sql": "string",
  • "severity": 0,
  • "status": "running",
  • "trigger_query": {
    },
  • "trigger_sql": "string"
}

resolve a triggered alert

Manually resolve a triggered alert so that it can be triggered again by the trigger event in the future.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

alert ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

start an alert

Start the alert with the given ID. If the alert is already running, the API does nothing and returns 204.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Alert ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

stop an alert

Stop the alert with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

alert ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

API keys v1beta2

list API keys

Get all API keys created by current user. The tenant owner will get all the API keys regardless of the creator.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an API key

Create a new API key with optional expiration, the created API key represents the owner thus has the same permissions as the owner

Authorizations:
ApiKeyAuth
Request Body schema: application/json

API Key parameters

expire_at
string <RFC3339>

define the expiration time of the API key by specifying the exact date time, cannot use with expire_in

expire_in
string

define the expiration time of the API key by specifying the amount of time to count from now, cannot use with expire_at

name
string

the name of the API key.

  • If name is speicfied, the masked API key will be appended to the end of the name (e.g. myAPIKey (vthm****OjXG)).
  • If name is not speicfied, the masked API key will be used as the name (e.g. vthm****OjXG).

Responses

Request samples

Content type
application/json
{
  • "expire_at": "2022-06-07T12:00:00Z08:00",
  • "expire_in": "24h",
  • "name": "myAPIKey"
}

Response samples

Content type
application/json
{
  • "api_key": "vthm5o5ENm4TaX5RcixG+DB8q9ALQtrU3VlfQBVFv1lQauWeDXR87MI5kOjXG",
  • "created_at": 1257894000,
  • "created_by": {
    },
  • "expire_at": 1257894000,
  • "id": "string",
  • "name": "myAPIKey (vthm****OjXG)",
  • "permissions": [
    ]
}

delete an API key

Delete the API key with the givin ID. The tenant owner is able to delete the API key regardless of the creator.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

API key ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

Dashboards v1beta2

list dashboards

Get all dashboards.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a dashboard

Create a dashboard.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

dashboard request parameters

description
string
name
required
string
Array of objects (dashboard.Panel)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "panels": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "string",
  • "id": "string",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "string",
  • "panels": [
    ]
}

delete a dashboard

Delete the dashboard with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

dashboard ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a dashboard

get a dashboard.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

dashboard ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "string",
  • "id": "string",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "string",
  • "panels": [
    ]
}

update a dashboard

Update the specific dashboard with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

dashboard ID

Request Body schema: application/json
required

update dashboard request parameters

description
string
name
required
string
Array of objects (dashboard.Panel)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "panels": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "string",
  • "id": "string",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "string",
  • "panels": [
    ]
}

External streams v1beta2

list external streams

Get all external streams.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an external stream

Create an external stream.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create external stream request parameters

Array of objects (ColumnDef)

Required if this is a kafka external stream

description
string
name
required
string
required
Array of objects (StreamSetting)

Responses

Request samples

Content type
application/json
{
  • "columns": [
    ],
  • "description": "a sample kafka external stream",
  • "name": "external_kafka",
  • "settings": [
    ]
}

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "description": "a sample kafka external stream",
  • "name": "external_kafka",
  • "settings": [
    ]
}

delete an external stream

Delete the external stream with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

external stream name

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get an external stream

Get the external stream with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

external stream name

Responses

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my test stream",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "test_external_stream",
  • "settings": [
    ]
}

get the stats of an external stream

Get the stats of an external stream with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

external stream name

query Parameters
historyDays
integer

number of days of the history metrics, must be >= 1 and <= 7 if set

Responses

Response samples

Content type
application/json
{
  • "earliest_event": "2023-02-01T01:02:03.456Z",
  • "historical_data_bytes": 234567,
  • "history": [
    ],
  • "latest_event": "2023-02-13T07:08:09.012Z",
  • "read_bps": 0,
  • "read_eps": 0,
  • "row_count": 20,
  • "streaming_data_bytes": 12345,
  • "written_bps": 0,
  • "written_eps": 0
}

preview an external stream

Preview an external stream.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

preview external stream request parameters

count
integer

Number of preview events. Defaulted to 1

offset
string
Enum: "earliest" "latest"

Preview from the earliest or latest offset of the stream. Defaulted to latest

required
Array of objects (StreamSetting)
timeout
integer

Preview timeout in seconds. Defaulted to 60

Responses

Request samples

Content type
application/json
{
  • "count": 1,
  • "offset": "latest",
  • "settings": [
    ],
  • "timeout": 60
}

Response samples

Content type
application/json
[
  • {
    }
]

External tables v1beta2

list external tables

Get all external tables.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an external table

Create an external table.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create external table request parameters

description
string
name
required
string
required
Array of objects (StreamSetting)

Responses

Request samples

Content type
application/json
{
  • "description": "a sample kafka external stream",
  • "name": "external_kafka",
  • "settings": [
    ]
}

Response samples

Content type
application/json
{
  • "description": "a sample kafka external stream",
  • "name": "external_kafka",
  • "settings": [
    ]
}

delete an external table

Delete the external table with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

external table name

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get an external table

Get the external table with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

external table name

Responses

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my test stream",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "test_external_stream",
  • "settings": [
    ]
}

Queries v1beta2

format a query

Format the given query and make it easy to read.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

the query SQL to be formatted

sql
string

Responses

Request samples

Content type
application/json
{
  • "sql": "string"
}

Response samples

Content type
application/json
{
  • "sql": "string"
}

list queries

Get all queries.

Authorizations:
ApiKeyAuth
query Parameters
tag
string

filter by tag

Responses

Response samples

Content type
application/json
[
  • {
    }
]

execute a query and return the results

Execute a query and return the results.

  • If the request fails, the response content type will be application/json. Please refer to the failure codes in Responses section below.
  • If the query is executed successfully, the response content type will be text/event-stream. For SSE There are 3 types of data that will be sent to SSE channel
  1. Query (type query): The first event of the result will ALWAYS be this type.
  2. Metrics (type metrics): The query metrics in JSON. They will be sent every 1 seconds.
  3. Data (the type is empty): The query result. Notice on data encoding Due to the limited data type supported by JSON (https://datatracker.ietf.org/doc/html/rfc4627#section-2.1), we use the following rules to encode result.
  4. For infinity, -infinity and NaN, we will enable them as string with value "inf", "-inf", "nan"
  5. For any big int type such as (u)int128, (u)int256, we will encode it as string.
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

query request parameters

object (BatchingPolicy)
description
string
name
string
sql
required
string
tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "batching_policy": {
    },
  • "description": "string",
  • "name": "string",
  • "sql": "string",
  • "tags": [
    ]
}

Response samples

Content type
{
  • "analysis": {
    },
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "ad-hoc streaming query",
  • "duration": 10,
  • "end_time": 1689809152,
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "test_query",
  • "response_time": 1,
  • "result": {
    },
  • "sinks": {
    },
  • "sql": "select * from iot",
  • "start_time": 1689809142,
  • "status": "running",
  • "tags": [
    ],
  • "timeColumns": {
    }
}

delete a query

Delete the query with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

query ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a query

Get the query with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

query ID

Responses

Response samples

Content type
application/json
{
  • "analysis": {
    },
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "ad-hoc streaming query",
  • "duration": 10,
  • "end_time": 1689809152,
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "test_query",
  • "response_time": 1,
  • "result": {
    },
  • "sinks": {
    },
  • "sql": "select * from iot",
  • "start_time": 1689809142,
  • "status": "running",
  • "tags": [
    ],
  • "timeColumns": {
    }
}

cancel a query

Cancel the query with the given ID. If given query is not running, the request will do nothing. Otherwise, the query will be canceled and the status will be set to canceled

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

query ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get the pipeline for a query

get the pipeline for a query

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

query ID

Responses

Response samples

Content type
application/json
{
  • "edges": [
    ],
  • "nodes": [
    ]
}

analyze sql

analyze sql

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

sql request parameters

sql
string

Responses

Request samples

Content type
application/json
{
  • "sql": "string"
}

Response samples

Content type
application/json
{
  • "group_by_columns": [
    ],
  • "has_aggr": true,
  • "has_subquery": true,
  • "has_table_join": true,
  • "has_union": true,
  • "is_streaming": true,
  • "original_query": "string",
  • "query_type": "string",
  • "required_columns": [
    ],
  • "result_columns": [
    ],
  • "rewritten_query": "string"
}

Metrics v1beta2

query global metrics

query global metrics.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "storage": 0
}

Invitations v1beta2

list invitations

Get all invitations.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an invitation

Invite an user to the current tenant.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create invitation request parameters

email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

delete an invitation

Delete the invitation with the given ID. Deleting the invitation will remove the user from current workspace.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

invitation ID

Responses

MaterializedViews v1beta2

list materialize view

Get all materialize view.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a materialize view

Create a materialize view. There are two different types of the materialize view, please refer to the documentation of MaterializedView for more details.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create MaterializedView request parameters

description
string
logstore_retention_bytes
integer

The max size a stream can grow. Any non-positive value means unlimited size. Defaulted to 10 GiB.

logstore_retention_ms
integer

The max time the data can be retained in the stream. Any non-positive value means unlimited time. Defaulted to 7 days.

name
required
string

View name should only contain a maximum of 64 letters, numbers, or _, and start with a letter

query
required
string
target_stream
string

This option is applicable only for materialized view. Specify this when you want to have multiple materialized views sink to the same target stream.

ttl_expression
string

Responses

Request samples

Content type
application/json
{
  • "description": "the description of my_test_view",
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "name": "my_test_view",
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "target_stream": "string",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 28 DAY"
}

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "description for my_view",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "name": "my_view",
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "target_stream": "high_speed_cars",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 7 DAY"
}

delete a materialized view

Delete the materialized view with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

MaterializedView name

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a materialize view

Get a materialize view with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

MaterializedView name

Responses

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "description for my_view",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "name": "my_view",
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "target_stream": "high_speed_cars",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 7 DAY"
}

update a materialize view

Update the specific materialize view with the given name. Updating the query of a materialized view is not allowed

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

name of the MaterializedView

Request Body schema: application/json
required

update MaterializedView request parameters

description
string
logstore_retention_bytes
integer

The max size a stream can grow. Any non-positive value means unlimited size. Defaulted to 10 GiB.

logstore_retention_ms
integer

The max time the data can be retained in the stream. Any non-positive value means unlimited time. Defaulted to 7 days.

query
string
ttl_expression
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "query": "string",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 28 DAY"
}

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get the stats of a materialize view

Get the stats of a materialize view with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

MaterializedView name

query Parameters
historyDays
integer

number of days of the history metrics, must be >= 1 and <= 7 if set

Responses

Response samples

Content type
application/json
{
  • "earliest_event": "2023-02-01T01:02:03.456Z",
  • "historical_data_bytes": 234567,
  • "history": [
    ],
  • "latest_event": "2023-02-13T07:08:09.012Z",
  • "nodes": [
    ],
  • "read_bps": 0,
  • "read_eps": 0,
  • "row_count": 20,
  • "streaming_data_bytes": 12345,
  • "written_bps": 0,
  • "written_eps": 0
}

Users v1beta2

list roles

Get all roles.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • "admin"
]

list users

list users.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create user

create a user.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create user request parameters

password
required
string
role
string
username
required
string

Responses

Request samples

Content type
application/json
{
  • "password": "qwekjds45",
  • "role": "admin",
  • "username": "myname"
}

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

delete a user

delete a user.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get user

get a user.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "role": "admin",
  • "username": "myname"
}

update user

update a user.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

update user request parameters

password
string
role
string

Responses

Request samples

Content type
application/json
{
  • "password": "qwekjds45",
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

Saved queries v1beta2

list Saved queries

Get all saved queries

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an saved query

Create a new saved query.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

saved query parameters

description
string
name
required
string
sql
required
string
tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "sql": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "get the latest data from iot stream",
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "streaming_iot",
  • "sql": "select * from iot",
  • "tags": [
    ]
}

delete a saved query

Delete the saved query with the givin ID

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

saved query ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a saved query

Get a saved query.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

saved query ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "get the latest data from iot stream",
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "streaming_iot",
  • "sql": "select * from iot",
  • "tags": [
    ]
}

update a saved query

Update the specific saved query with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

saved query ID

Request Body schema: application/json
required

update saved query request parameters

description
string
name
required
string
sql
required
string
tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "sql": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "get the latest data from iot stream",
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "streaming_iot",
  • "sql": "select * from iot",
  • "tags": [
    ]
}

Schemas v1beta2

list schemas

Get all schemas.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a schema

Create a schema

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create Schema request parameters

content
required
string
name
required
string
type
required
string
Value: "Protobuf"

Responses

Request samples

Content type
application/json
{
  • "content": "",
  • "name": "my_schema",
  • "type": "Protobuf"
}

Response samples

Content type
application/json
{
  • "content": "",
  • "name": "my_schema",
  • "type": "Protobuf"
}

delete a schema

Delete the schema with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

schema

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a schema

get schema with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

schema name

Responses

Response samples

Content type
application/json
{
  • "content": "",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "my_schema",
  • "type": "Protobuf"
}

update a schema

Update the specific schema with the given content.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

update Schema request parameters

content
required
string
name
required
string
type
required
string
Value: "Protobuf"

Responses

Request samples

Content type
application/json
{
  • "content": "",
  • "name": "my_schema",
  • "type": "Protobuf"
}

Response samples

Content type
application/json
{
  • "content": "",
  • "name": "my_schema",
  • "type": "Protobuf"
}

Sinks v1beta2

list sinks

Get all sinks

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a sink

Create a sink. Please refer to the documentation of sink for more details.

Supported Sink Types:

http

  • url: specifies the URL of http
  • content_type: optional, specifies the content type
  • http_method: optional, specifies the http method, default to POST
  • payload_field: optional, the payload of the http request, use {{ .field_name }} to replace the field of query result you want to reference
  • http_header: optional, http header object, default to {}
  • paralism: optional, specifies the paralism number schema, default to 1
  • retries: optional, specifies the retries number, default to 0
  • retry_interval: optional, specifies the interval between retries, default to 10s
  • timeout: optional, http timeout interval, default to 10s
  • oauth2: specifies oauth2 configuration
  • oauth2.enabled: optional, whether to enable oauth2, default to false
  • oauth2.client_key: optional, client key
  • oauth2.client_secret: optinoal, client secret
  • oauth2.token_url: optional, token url
  • oauth2.scopes: optional, list of scope strings

slack

  • url: the webhook URL of the slack channel, which is considered as a secret
  • template: optional, the template used to send query result to slack, use {{ .field_name }} to replace the field of query result you want to reference. in case it is empty, will encode the event into JSON format
  • header: optional, the http header, default to {}
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create sink request parameters

description
string
name
required
string

Sink name should only contain a maximum of 64 letters, numbers, or _, and start with a letter

object

Additional properties that required to write the data to the sink (e.g. broker url). Please refer to the documentation for this sink type

query
required
string
type
required
string

Available types: [slack, http, redpanda_connect]. Additional configurations such as broker url and etc. should be passed through properties

Responses

Request samples

Content type
application/json
{
  • "description": "write data to http endpoint",
  • "name": "write_to_http",
  • "properties": {
    },
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "type": "http"
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "write data to http endpoint",
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "write_to_http",
  • "plan": {
    },
  • "properties": {
    },
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "status": "running",
  • "type": "http"
}

delete a sink

Delete a sink with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

sink ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a sink

Get a sink with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

sink ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "write data to http endpoint",
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "write_to_http",
  • "plan": {
    },
  • "properties": {
    },
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "status": "running",
  • "type": "http"
}

update a sink

Update the specific sink with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

sink ID

Request Body schema: application/json
required

update sink request parameters

description
string
name
required
string

Sink name should only contain a maximum of 64 letters, numbers, or _, and start with a letter

object

Additional properties that required to write the data to the sink (e.g. broker url). Please refer to the documentation for this sink type

query
required
string
type
required
string

Available types: [slack, http, redpanda_connect]. Additional configurations such as broker url and etc. should be passed through properties

Responses

Request samples

Content type
application/json
{
  • "description": "write data to http endpoint",
  • "name": "write_to_http",
  • "properties": {
    },
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "type": "http"
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "write data to http endpoint",
  • "id": "UUID",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "write_to_http",
  • "plan": {
    },
  • "properties": {
    },
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "status": "running",
  • "type": "http"
}

start a sink

Start the sink with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

sink ID

query Parameters
sync
boolean

Whether to run the operation synchronously (default: true)

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get the stats of a sink

Get the stats of a sink with the given id.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

sink ID

query Parameters
error_log_time_range
required
string
Example: error_log_time_range=1d
metrics_time_range
required
string
Example: metrics_time_range=10m

Responses

Response samples

Content type
application/json
{
  • "earliest_event": "2023-02-01T01:02:03.456Z",
  • "errors": [
    ],
  • "failure_count": 1,
  • "historical_data_bytes": 234567,
  • "history": [
    ],
  • "latest_event": "2023-02-13T07:08:09.012Z",
  • "nodes": [
    ],
  • "read_bps": 0,
  • "read_eps": 0,
  • "row_count": 20,
  • "streaming_data_bytes": 12345,
  • "success_count": 99,
  • "throughput": [
    ],
  • "written_bps": 0,
  • "written_eps": 0
}

stop a sink

Stop the sink with the given ID from sending out data.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

sink ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

Sources v1beta2

preview a source

Get sample events from the source with the given ID. Please refer to create source for more details regarding type and properties.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

source properties for preview

object

See CreateSourceRequest

size
integer

Number of preview events, works together with Timeout.

timeout
string

Indicates how long should preview last to fetch the desired amount of data indicated by size A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

type
required
string

See CreateSourceRequest

Responses

Request samples

Content type
application/json
{
  • "properties": {
    },
  • "size": 1,
  • "timeout": "1m",
  • "type": "websocket"
}

Response samples

Content type
application/json
[
  • {
    }
]

list sources

Get all sources.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a source

Create a source. Please refer to the documentation of source for more details.

Supported Source Types:

stream_generator

  • template: specifies the template used to generate data, support iot,user_logins,devops
  • interval: optional, specifies the event interval. for example 200ms, default to 200ms

websocket

  • url: specifies the URL of the websocket server url
  • data_type: specifies the data type to use for creating the stream. support json,text,
  • open_message: optional, a message send to the server upon connection
  • open_message_type: optional, a flag to indicate the data type of open_message. support text,binary

nats

  • url: a list of URLs to connect to. for example [nats://127.0.0.1:4222]
  • subject: a subject to consume from. Supports wildcards for consuming multiple subjects.
  • data_type: specifies the data type to use for creating the stream. support json,text,
  • queue: optional, a queue group to consume as
  • nak_delay: optional, a delay duration on redelivering a message when negatively acknowledged.
  • prefetch_count: optional, the maximum number of messages to pull at a time. default to 524288
  • tls.disable: optional, If set to true, disables TLS encryption, default to false
  • tls.skip_verify_server: optional, If set to true, skips server certificate verification when using TLS, default to false

nats_jetstream

  • url: a list of URLs to connect to. for example [nats://127.0.0.1:4222]
  • subject: a subject to consume from. Supports wildcards for consuming multiple subjects.
  • data_type: specifies the data type to use for creating the stream. support json,text,
  • queue: optional, a queue group to consume as
  • durable: optional, preserve the state of your consumer under a durable name
  • stream: optional, a stream to consume from. either a subject or stream must be specified
  • deliver: optional, determines which messages to deliver when consuming without a durable subscriber. support all,last. default to all
  • bind: optional, a bool indicates that the subscription should use an existing consumer.
  • ack_wait: optional, the maximum amount of time NATS server should wait for an ack from consumer. default to 30s
  • max_ack_pending: optional, the maximum number of outstanding acks to be allowed before consuming is halted. default to 1024
  • tls.disable: optional, If set to true, disables TLS encryption, default to false
  • tls.skip_verify_server: optional, If set to true, skips server certificate verification when using TLS, default to false
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create source request parameters

description
string
name
required
string

Source name should only contain a maximum of 64 letters, numbers, or _, and start with a letter

object

Additional properties that required to read the data from source (e.g. broker url). Please refer to the documentation for this source type

stream
required
string

The name of the target stream that this source writes to. The stream needs to be created first.

type
required
string

Available types: [stream_generator, websocket, nats, nats_jetstream, redpanda_connect]. Additional configurations such as broker url and etc. should be passed through properties

Responses

Request samples

Content type
application/json
{
  • "description": "read from my first source",
  • "name": "my_first_source",
  • "properties": {
    },
  • "stream": "dest_stream",
  • "type": "websocket"
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "read data from a websocket endpoint",
  • "id": "source_id",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "my_websocket_source",
  • "properties": {
    },
  • "start_time": 1680301788,
  • "status": "running",
  • "stream": "websocket_stream",
  • "type": "websocket"
}

delete a source

Delete the source with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

source ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a source

Get a source with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

source ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "read data from a websocket endpoint",
  • "id": "source_id",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "my_websocket_source",
  • "properties": {
    },
  • "start_time": 1680301788,
  • "status": "running",
  • "stream": "websocket_stream",
  • "type": "websocket"
}

update a source

Update the specific source with the given ID. Only stopped sources can be updated.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

source ID

Request Body schema: application/json
required

update source request parameters

description
string
name
string

Source name should only contain a maximum of 64 letters, numbers, or _, and start with a letter

object

Additional properties that required to read the data from source (e.g. broker url). Please refer to the documentation for this source type

stream
string

The name of the target stream that this source writes to. The stream needs to be created first.

Responses

Request samples

Content type
application/json
{
  • "description": "new description for the source",
  • "name": "new_source_name",
  • "properties": {
    },
  • "stream": "new_stream"
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "read data from a websocket endpoint",
  • "id": "source_id",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "message": "string",
  • "name": "my_websocket_source",
  • "properties": {
    },
  • "start_time": 1680301788,
  • "status": "running",
  • "stream": "websocket_stream",
  • "type": "websocket"
}

start a source

Start the source with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

source ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get the stats of a source

Get the stats of a source with the given id.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

source ID

query Parameters
error_log_time_range
required
string
Example: error_log_time_range=1d
metrics_time_range
required
string
Example: metrics_time_range=10m

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "failure_count": 1,
  • "success_count": 99,
  • "throughput": [
    ]
}

stop a source

Stop the source with the given ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

source ID

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

Streams v1beta2

list streams

Get all streams.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a stream

Create a stream. Please refer to the documentation of stream for more details.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create stream request parameters

Array of objects (ColumnFamily)

Columns in column families shall have no overlap with primary keys

Array of objects (ColumnDef)
description
string
engine
string
Value: "MutableStream"
event_time_column
string

This column will be used as the event time if specified

event_time_timezone
string

The timezone of the TimestampColumn

logstore_retention_bytes
integer

The max size a stream can grow. Any non-positive value means unlimited size. Defaulted to 10 GiB.

logstore_retention_ms
integer

The max time the data can be retained in the stream. Any non-positive value means unlimited time. Defaulted to 7 days.

mode
string
Enum: "append" "changelog" "changelog_kv" "versioned_kv"

Storage mode of stream. Defaulted to append.

name
required
string

Stream name should only contain a maximum of 64 letters, numbers, or _, and start with a letter

order_by_expression
string
order_by_granularity
string
partition_by_granularity
string
primary_key
string

Expression of primary key, required in changelog_kv and versioned_kv mode

replication_factor
integer
Array of objects (SecondaryIndex)
shards
integer
ttl_expression
string

Responses

Request samples

Content type
application/json
{
  • "column_families": [
    ],
  • "columns": [
    ],
  • "description": "my first stream",
  • "engine": "MutableStream",
  • "event_time_column": "time",
  • "event_time_timezone": "UTC",
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "mode": "append",
  • "name": "test_stream",
  • "order_by_expression": "string",
  • "order_by_granularity": "string",
  • "partition_by_granularity": "string",
  • "primary_key": "string",
  • "replication_factor": 0,
  • "secondary_indexes": [
    ],
  • "shards": 0,
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 7 DAY"
}

Response samples

Content type
application/json
{
  • "column_families": [
    ],
  • "columns": [
    ],
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my test stream",
  • "engine": "Stream",
  • "is_external": false,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "logstore_retention_bytes": 1073741824,
  • "logstore_retention_ms": 86400000,
  • "mode": "append",
  • "name": "test_stream",
  • "primary_key": "string",
  • "secondary_indexes": [
    ],
  • "ttl": "to_datetime(_tp_time) + INTERVAL 7 DAY",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 7 DAY"
}

delete a stream

Delete the stream with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

stream name

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a stream

Get a stream with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

stream name

Responses

Response samples

Content type
application/json
{
  • "column_families": [
    ],
  • "columns": [
    ],
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my test stream",
  • "engine": "Stream",
  • "is_external": false,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "logstore_retention_bytes": 1073741824,
  • "logstore_retention_ms": 86400000,
  • "mode": "append",
  • "name": "test_stream",
  • "primary_key": "string",
  • "secondary_indexes": [
    ],
  • "ttl": "to_datetime(_tp_time) + INTERVAL 7 DAY",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 7 DAY"
}

update a stream

Update the specific stream with the given name. Right now it only supports updating data retention-related settings. Altering stream or updating external stream is not supported yet.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

name of the stream

Request Body schema: application/json
required

update stream request parameters

description
string
logstore_retention_bytes
integer

The max size a stream can grow. Any non-positive value means unlimited size. Defaulted to 10 GiB.

logstore_retention_ms
integer

The max time the data can be retained in the stream. Any non-positive value means unlimited time. Defaulted to 7 days.

ttl_expression
string

Responses

Request samples

Content type
application/json
{
  • "description": "new description",
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 28 DAY"
}

Response samples

Content type
application/json
{
  • "column_families": [
    ],
  • "columns": [
    ],
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my test stream",
  • "engine": "Stream",
  • "is_external": false,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "logstore_retention_bytes": 1073741824,
  • "logstore_retention_ms": 86400000,
  • "mode": "append",
  • "name": "test_stream",
  • "primary_key": "string",
  • "secondary_indexes": [
    ],
  • "ttl": "to_datetime(_tp_time) + INTERVAL 7 DAY",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 7 DAY"
}

ingest data

Ingest data to a stream with the given name. For formats are supported:

  • compact JSON: when Content-Type is set to one of application/json, application/json;format=compact, application/vnd.timeplus+json, application/vnd.timeplus+json;format=compat, or set format query parameter with value compact. And this is the API's default format.
  • JSON stream: when Content-Type is set to one of application/json;format=streaming, application/vnd.timeplus+json;format=streaming, or set format query parameter with value streaming.
  • raw string: when Content-Type is set to one of text/plain, text/plain;format=raw, or set format query parameter with value raw.
  • string lines: when Content-Type is set to text/plain;format=lines, or set format query parameter with value lines.
  • refer to https://docs.timeplus.com/docs/ingest-api for more information *
Authorizations:
ApiKeyAuth
path Parameters
name
required
string

stream name

query Parameters
format
string
Enum: "compact" "streaming" "raw" "lines"

enfoce payload format, if it is set, it overwrite the Content-Type header

Request Body schema:
required

ingest data

columns
required
Array of strings
data
required
Array of any[ items ]

Responses

Request samples

Content type
{
  • "columns": [
    ],
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get the stats of a stream

Get the stats of a stream with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

stream name

query Parameters
historyDays
integer

number of days of the history metrics, must be >= 1 and <= 7 if set

Responses

Response samples

Content type
application/json
{
  • "earliest_event": "2023-02-01T01:02:03.456Z",
  • "historical_data_bytes": 234567,
  • "history": [
    ],
  • "latest_event": "2023-02-13T07:08:09.012Z",
  • "read_bps": 0,
  • "read_eps": 0,
  • "row_count": 20,
  • "streaming_data_bytes": 12345,
  • "written_bps": 0,
  • "written_eps": 0
}

Subscription v1beta2

get current subscription

Get the status of current subscription.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "customer": {
    },
  • "payment": {
    },
  • "spec": {
    },
  • "subscription_plan": "Free Trial"
}

Topology v1beta2

get topology graph

Get topology graph of all existings resources.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "edges": [
    ],
  • "nodes": [
    ]
}

UDFs v1beta2

list user-defined functions

Get all user-defined functions.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an user-defined function

Create an user-defined function.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create UDF request parameters

Array of objects (UDFArgument)

The input argument of the UDF

  • For UDA: the number and type of arguments should be consistent with the main function of UDA. the type should be the data types of proton not javascript types. It only supports int8/16/32/64, uint8/16/32/64,
object (UDFAuthContext)
auth_method
string

Only valid when type is remote. This field is used to set the authentication method for remote UDF. It can be either auth_header or none. When auth_header is set, you can configure auth_context to specify the HTTP header that be sent the remote URL

created_at
string
object (Owner)
description
string
is_aggregation
boolean

Only valid when type is 'javascript'. Whether it is an aggregation function.

last_updated_at
string
object (Owner)
name
required
string
return_type
string

The erturn type of the UDF

  • For UDA: if it returns a single value, the return type is the corresponding data type of Timeplus. It supports the same types of input arguments, except for datetime, it only supports DateTime64(3).
source
string

Only valid when type is 'javascript' The source code of the UDA. There are functions to be defined:

  • main function: with the same name as UDA. Timeplus calls this function for each input row. The main function can return two types of result: object or simple data type
    • If it returns an object, the object is like {“emit”: true, “result”: …}. ‘Emit’ (boolean) property tells Timeplus whether or not the result should emit. ‘result’ is the current aggregate result, if ‘emit’ is false, the result will be ignored by Timeplus. Timeplus will convert the ‘result’ property of v8 to the data types defined when creating UDA.
    • If it returns a simple data type, Timeplus considers the return data as the result to be emitted immediately. It converts the return data to the corresponding data type and Timeplus emits the aggregating result.
    • Once UDA tells Timeplus to emit the data, UDA takes the full responsibility to clear the internal state, prepare and restart a new aggregating window, et al.
  • state function: which returns the serialized state of all internal states of UDA in string. The UDA takes the responsibility therefore Timeplus can choose to persist the internal state of UDA for query recovery.
  • init function: the input of this function is the string of serialized state of the internal states UDA. Timeplus calls this function when it wants to recover the aggregation function with the persisted internal state.
type
required
string

Either javascript or remote

url
string

Only valid when type is remote.

Responses

Request samples

Content type
application/json
{
  • "arguments": [
    ],
  • "auth_context": {
    },
  • "auth_method": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my first UDF",
  • "is_aggregation": true,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "sum_2",
  • "return_type": "float64",
  • "source": "string",
  • "type": "remote",
  • "url": "http://mydomain.com/trigger"
}

Response samples

Content type
application/json
{
  • "arguments": [
    ],
  • "auth_context": {
    },
  • "auth_method": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my first UDF",
  • "is_aggregation": true,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "sum_2",
  • "return_type": "float64",
  • "source": "string",
  • "type": "remote",
  • "url": "http://mydomain.com/trigger"
}

delete an user-defined function

Delete the user-defined function with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

user-defined function name

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get an user-defined function

get the user-defined function with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

user-defined function name

Responses

Response samples

Content type
application/json
{
  • "arguments": [
    ],
  • "auth_context": {
    },
  • "auth_method": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my first UDF",
  • "is_aggregation": true,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "sum_2",
  • "return_type": "float64",
  • "source": "string",
  • "type": "remote",
  • "url": "http://mydomain.com/trigger"
}

update an user-defined function

Update the specific user-defined function with the given name.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

update UDF request parameters

Array of objects (UDFArgument)

The input argument of the UDF

  • For UDA: the number and type of arguments should be consistent with the main function of UDA. the type should be the data types of proton not javascript types. It only supports int8/16/32/64, uint8/16/32/64,
object (UDFAuthContext)
auth_method
string

Only valid when type is remote. This field is used to set the authentication method for remote UDF. It can be either auth_header or none. When auth_header is set, you can configure auth_context to specify the HTTP header that be sent the remote URL

created_at
string
object (Owner)
description
string
is_aggregation
boolean

Only valid when type is 'javascript'. Whether it is an aggregation function.

last_updated_at
string
object (Owner)
name
required
string
return_type
string

The erturn type of the UDF

  • For UDA: if it returns a single value, the return type is the corresponding data type of Timeplus. It supports the same types of input arguments, except for datetime, it only supports DateTime64(3).
source
string

Only valid when type is 'javascript' The source code of the UDA. There are functions to be defined:

  • main function: with the same name as UDA. Timeplus calls this function for each input row. The main function can return two types of result: object or simple data type
    • If it returns an object, the object is like {“emit”: true, “result”: …}. ‘Emit’ (boolean) property tells Timeplus whether or not the result should emit. ‘result’ is the current aggregate result, if ‘emit’ is false, the result will be ignored by Timeplus. Timeplus will convert the ‘result’ property of v8 to the data types defined when creating UDA.
    • If it returns a simple data type, Timeplus considers the return data as the result to be emitted immediately. It converts the return data to the corresponding data type and Timeplus emits the aggregating result.
    • Once UDA tells Timeplus to emit the data, UDA takes the full responsibility to clear the internal state, prepare and restart a new aggregating window, et al.
  • state function: which returns the serialized state of all internal states of UDA in string. The UDA takes the responsibility therefore Timeplus can choose to persist the internal state of UDA for query recovery.
  • init function: the input of this function is the string of serialized state of the internal states UDA. Timeplus calls this function when it wants to recover the aggregation function with the persisted internal state.
type
required
string

Either javascript or remote

url
string

Only valid when type is remote.

Responses

Request samples

Content type
application/json
{
  • "arguments": [
    ],
  • "auth_context": {
    },
  • "auth_method": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my first UDF",
  • "is_aggregation": true,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "sum_2",
  • "return_type": "float64",
  • "source": "string",
  • "type": "remote",
  • "url": "http://mydomain.com/trigger"
}

Response samples

Content type
application/json
{
  • "arguments": [
    ],
  • "auth_context": {
    },
  • "auth_method": "string",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "my first UDF",
  • "is_aggregation": true,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "sum_2",
  • "return_type": "float64",
  • "source": "string",
  • "type": "remote",
  • "url": "http://mydomain.com/trigger"
}

Views v1beta2

list views

Get all views.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a view

Create a view. There are two different types of the view, please refer to the documentation of view for more details.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

create view request parameters

description
string
logstore_retention_bytes
integer

The max size a stream can grow. Any non-positive value means unlimited size. Defaulted to 10 GiB.

logstore_retention_ms
integer

The max time the data can be retained in the stream. Any non-positive value means unlimited time. Defaulted to 7 days.

materialized
boolean
Default: false
name
required
string

View name should only contain a maximum of 64 letters, numbers, or _, and start with a letter

query
required
string
target_stream
string

This option is applicable only when materialized is true. Specify this when you want to have multiple materialized views sink to the same target stream.

ttl_expression
string

Responses

Request samples

Content type
application/json
{
  • "description": "the description of my_test_view",
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "materialized": false,
  • "name": "my_test_view",
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "target_stream": "string",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 28 DAY"
}

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "description for my_view",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "materialized": false,
  • "name": "my_view",
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "target_stream": "high_speed_cars",
  • "ttl": "to_datetime(_tp_time) + INTERVAL 7 DAY",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 7 DAY"
}

delete a view

Delete the view with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

view name

Responses

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get a view

Get a view with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

view name

Responses

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "description for my_view",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "materialized": false,
  • "name": "my_view",
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "target_stream": "high_speed_cars",
  • "ttl": "to_datetime(_tp_time) + INTERVAL 7 DAY",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 7 DAY"
}

update a view

Update the specific view with the given name. Updating the query of a materialized view is not allowed

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

name of the view

Request Body schema: application/json
required

update view request parameters

description
string
logstore_retention_bytes
integer

The max size a stream can grow. Any non-positive value means unlimited size. Defaulted to 10 GiB.

logstore_retention_ms
integer

The max time the data can be retained in the stream. Any non-positive value means unlimited time. Defaulted to 7 days.

query
string
ttl_expression
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "query": "string",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 28 DAY"
}

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}

get the stats of a view

Get the stats of a view with the given name.

Authorizations:
ApiKeyAuth
path Parameters
name
required
string

view name

query Parameters
historyDays
integer

number of days of the history metrics, must be >= 1 and <= 7 if set

Responses

Response samples

Content type
application/json
{
  • "earliest_event": "2023-02-01T01:02:03.456Z",
  • "historical_data_bytes": 234567,
  • "history": [
    ],
  • "latest_event": "2023-02-13T07:08:09.012Z",
  • "nodes": [
    ],
  • "read_bps": 0,
  • "read_eps": 0,
  • "row_count": 20,
  • "streaming_data_bytes": 12345,
  • "written_bps": 0,
  • "written_eps": 0
}

Workspace v1beta2

get current workspace

Get the basic information about the current workspace.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "free_trial_end_date": "2023-02-13T07:08:09.012Z",
  • "id": "t5abcd1e",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "name": "my_workspace",
  • "settings": {
    }
}

update current workspace

Update the settings of current workspace. For Timeplus cloud, only tenant owner can update the workspace. For Timeplus enterprise, there is no such check.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

update workspace request parameters

object (WorkspaceSettings)

Responses

Request samples

Content type
application/json
{
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "code": 57,
  • "message": "stream 'iot' exists",
  • "system": "proton"
}