API docs by Redocly

Timeplus Enterprise (v1)

Download OpenAPI specification:

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

Welcome to the Timeplus Enterprise REST API specification.

Misc

get the version information

Get the version information of all Timeplus components. If any component is not available, the version of the component will be unknown. If timeplusd is not available, the status code will be 503.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
{
  • "axion": {
    },
  • "neutron": {
    },
  • "orbit": {
    },
  • "product_name": "string",
  • "product_version": "string",
  • "proton": {
    }
}

Alerts v1beta2

list alerts

Get all alerts.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an alert

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

Authorizations:
BasicAuth
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:
BasicAuth
path Parameters
id
required
string

alert ID

Responses

Response samples

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

get an alert

Get an alert with the given ID.

Authorizations:
BasicAuth
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:
BasicAuth
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:
BasicAuth
path Parameters
id
required
string

alert ID

Responses

Response samples

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

start an alert

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

Authorizations:
BasicAuth
path Parameters
id
required
string

Alert ID

Responses

Response samples

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

stop an alert

Stop the alert with the given ID.

Authorizations:
BasicAuth
path Parameters
id
required
string

alert ID

Responses

Response samples

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

Topology v1beta2

get cluster info

Get cluster status.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

get topology graph

Get topology graph of all existings resources in a specific database.

Authorizations:
BasicAuth
query Parameters
db
string

database

extraResources
Array of strings

supported resource type: dashboard, schema, udf

Responses

Response samples

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

Dashboards v1beta2

list dashboards

Get all dashboards.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a dashboard

Create a dashboard.

Authorizations:
BasicAuth
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:
BasicAuth
path Parameters
id
required
string

dashboard ID

Responses

Response samples

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

get a dashboard

get a dashboard.

Authorizations:
BasicAuth
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:
BasicAuth
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": [
    ]
}

Databases v1beta2

list databases

Get all databases.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Dictionaries v1beta2

list dictionary

Get all dictionaries.

Authorizations:
BasicAuth
query Parameters
db
string

database

Responses

Response samples

Content type
application/json
[
  • {
    }
]

delete a dictionary

Delete the dictionary with the given name.

Authorizations:
BasicAuth
path Parameters
name
required
string

dictionary name

query Parameters
db
string

database

Responses

Response samples

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

get a dictionary

Get the dictionary with the given name.

Authorizations:
BasicAuth
path Parameters
name
required
string

dictionary name

query Parameters
db
string

database

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",
  • "query": "string"
}

Queries v1beta2

execute a historical query or DDL

Execute a historical query or DDL. The client is responsible for specifying type of the query. If the SQL is not determinstic or it is a streaming query, please please consider using queries endpoint.

  • If failed to execute, please refer to the error code.
  • If type is ddl and it is executed successfully, it will return 204 No Content.
  • If type is historical it is executed successfully, please refer to response 200
Authorizations:
BasicAuth
Request Body schema: application/json
required

query request parameters

object

Controls how often a batch of results will be flushed via SSE channel

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
application/json
{
  • "columns": [
    ],
  • "data": [
    ]
}

format a query

Format the given query and make it easy to read.

Authorizations:
BasicAuth
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:
BasicAuth
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. The client can submit any query type and the server will dynamically detect the query type and handle it differently. This endpoint should be used if the SQL is not deterministic. For example, the end users can type any SQL they want. If the SQL is deterministic, please consider using exec endpoint.

  • If this is a DDL query and it is executed successfully, it will return 204 No Content.
  • If this is a DDL query and it fails to be executed (e.g. wrong schema), the response content type will be application/json. Please refer to the failure codes in Responses section below.
  • If this is a select-like query and it is executed successfully, the response content type will be text/event-stream and the result will be streamed back to the client via this SSE channel.
  • If this is a select-like query and it fails to be executed (e.g. wrong schema), the response content type will be application/json. Please refer to the failure codes in Responses section below.

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:
BasicAuth
Request Body schema: application/json
required

query request parameters

object

Controls how often a batch of results will be flushed via SSE channel

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:
BasicAuth
path Parameters
id
required
string

query ID

Responses

Response samples

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

get a query

Get the query with the given ID.

Authorizations:
BasicAuth
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:
BasicAuth
path Parameters
id
required
string

query ID

Responses

Response samples

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

get the pipeline for a query

get the pipeline for a query

Authorizations:
BasicAuth
path Parameters
id
required
string

query ID

Responses

Response samples

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

analyze sql

analyze sql

Authorizations:
BasicAuth
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"
}

External streams v1beta2

list external streams

Get all external streams.

Authorizations:
BasicAuth
query Parameters
db
string

database

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an external stream

Create an external stream.

Authorizations:
BasicAuth
query Parameters
db
string

database

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:
BasicAuth
path Parameters
name
required
string

external stream name

query Parameters
db
string

database

Responses

Response samples

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

get an external stream

Get the external stream with the given name.

Authorizations:
BasicAuth
path Parameters
name
required
string

external stream name

query Parameters
db
string

database

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": [
    ],
  • "type": "string"
}

get the stats of an external stream

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

Authorizations:
BasicAuth
path Parameters
name
required
string

external stream name

query Parameters
db
string

database

historyDays
integer

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

Responses

Response samples

Content type
application/json
{
  • "history": [
    ],
  • "read_bps": 0,
  • "read_eps": 0,
  • "written_bps": 0,
  • "written_eps": 0
}

preview an external stream

Preview an external stream.

Authorizations:
BasicAuth
query Parameters
db
string

database

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:
BasicAuth
query Parameters
db
string

database

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an external table

Create an external table.

Authorizations:
BasicAuth
query Parameters
db
string

database

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:
BasicAuth
path Parameters
name
required
string

external table name

query Parameters
db
string

database

Responses

Response samples

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

get an external table

Get the external table with the given name.

Authorizations:
BasicAuth
path Parameters
name
required
string

external table name

query Parameters
db
string

database

Responses

Response samples

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

Metrics v1beta2

query global metrics

query global metrics.

Authorizations:
BasicAuth

Responses

Response samples

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

License v1beta2

list all licenses

list all licenses

Responses

Response samples

Content type
application/json
[
  • {
    }
]

upload and create a license

upload and create a license.

Request Body schema: application/x-www-form-urlencoded
required
key
required
string

encryption key for license file

file
required
string <binary>

license file

Responses

Response samples

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

create a trial license and start to use Timeplus

create a trial license and start to use Timeplus

Request Body schema: application/json
required

start trial parameters

allowTrack
boolean
password
string
userEmail
string
userName
string

Responses

Request samples

Content type
application/json
{
  • "allowTrack": true,
  • "password": "string",
  • "userEmail": "string",
  • "userName": "string"
}

Response samples

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

get the usage history

get the usage history. Note: The usage data will be available after the license has been active for at least 4 hours.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

get license validation result

get license validation result. Note: The validation results will be available after the license has been active for at least 4 hours.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

MaterializedViews v1beta2

list materialize view

Get all materialize view.

Authorizations:
BasicAuth
query Parameters
expand
boolean

whether the response should include optional metrics (status_code, status, status_ts, lagging, memory) or not

db
string

database

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:
BasicAuth
query Parameters
db
string

database

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

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",
  • "id": "string",
  • "lagging": 50,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "memory": 1048576,
  • "name": "my_view",
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "status": "Materialized view is not running on any node",
  • "status_code": 0,
  • "status_ts": 1737411240123,
  • "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:
BasicAuth
path Parameters
name
required
string

MaterializedView name

query Parameters
db
string

database

Responses

Response samples

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

get a materialize view

Get a materialize view with the given name.

Authorizations:
BasicAuth
path Parameters
name
required
string

MaterializedView name

query Parameters
db
string

database

Responses

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "description for my_view",
  • "id": "string",
  • "lagging": 50,
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "memory": 1048576,
  • "name": "my_view",
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "status": "Materialized view is not running on any node",
  • "status_code": 0,
  • "status_ts": 1737411240123,
  • "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:
BasicAuth
path Parameters
name
required
string

name of the MaterializedView

query Parameters
db
string

database

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": "timeplusd"
}

get the stats of a materialize view

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

Authorizations:
BasicAuth
path Parameters
name
required
string

MaterializedView name

query Parameters
db
string

database

historyDays
integer

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

granularity
string

granularity of the history metrics, default is 10m. Examples: [1m, 10m, 1h, 1d]

Responses

Response samples

Content type
application/json
{
  • "earliest_event": "2023-02-01T01:02:03.456Z",
  • "historical_data_bytes": 234567,
  • "history": [
    ],
  • "lagging": 50,
  • "latest_event": "2023-02-13T07:08:09.012Z",
  • "memory": 1048576,
  • "nodes": [
    ],
  • "read_bps": 0,
  • "read_eps": 0,
  • "row_count": 20,
  • "status": "Materialized view is not running on any node",
  • "status_code": 0,
  • "status_ts": 1737411240123,
  • "streaming_data_bytes": 12345,
  • "written_bps": 0,
  • "written_eps": 0
}

Users v1beta2

list roles

Get all roles.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
[
  • "admin"
]

list users

list users.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create user

create a user.

Authorizations:
BasicAuth
Request Body schema: application/json
required

create user request parameters

password
required
string
role
string
Enum: "admin" "read_only"
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": "timeplusd"
}

delete a user

delete a user.

Authorizations:
BasicAuth

Responses

Response samples

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

get user

get a user.

Authorizations:
BasicAuth

Responses

Response samples

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

update user

update a user.

Authorizations:
BasicAuth
Request Body schema: application/json
required

update user request parameters

password
string
role
string
Enum: "admin" "read_only"

Responses

Request samples

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

Response samples

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

Saved queries v1beta2

list Saved queries

Get all saved queries

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an saved query

Create a new saved query.

Authorizations:
BasicAuth
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": "string",
  • "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:
BasicAuth
path Parameters
id
required
string

saved query ID

Responses

Response samples

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

get a saved query

Get a saved query.

Authorizations:
BasicAuth
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": "string",
  • "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:
BasicAuth
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": "string",
  • "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:
BasicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a schema

Create a schema

Authorizations:
BasicAuth
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:
BasicAuth
path Parameters
name
required
string

schema

Responses

Response samples

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

get a schema

get schema with the given name.

Authorizations:
BasicAuth
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:
BasicAuth
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:
BasicAuth

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, you can use template (https://pkg.go.dev/text/template) to substitute 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 template 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:
BasicAuth
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": "string",
  • "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:
BasicAuth
path Parameters
id
required
string

sink ID

Responses

Response samples

Content type
application/json
[
  • "string"
]

get a sink

Get a sink with the given ID.

Authorizations:
BasicAuth
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": "string",
  • "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"
}

patch a sink

patch the specific sink with the given ID. The pipeline will be restarted and the checkpoint will be kept.

Authorizations:
BasicAuth
path Parameters
id
required
string

sink ID

Request Body schema: application/json
required

patch sink request parameters

description
string
name
string
object

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "properties": {
    }
}

Response samples

Content type
application/json
{
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "write data to http endpoint",
  • "id": "string",
  • "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"
}

[DEPRECATED] update a sink

Update the specific sink with the given ID.

Authorizations:
BasicAuth
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": "string",
  • "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"
}

get the logs of a sink

Get the logs of a sink with the given id.

Authorizations:
BasicAuth
path Parameters
id
required
string

sink ID

query Parameters
lines
required
integer

number of lines

Responses

Response samples

Content type
application/json
[
  • "string"
]

start a sink

Start the sink with the given ID.

Authorizations:
BasicAuth
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": "timeplusd"
}

get the stats of a sink

Get the stats of a sink with the given id.

Authorizations:
BasicAuth
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": [
    ],
  • "lagging": 50,
  • "latest_event": "2023-02-13T07:08:09.012Z",
  • "memory": 1048576,
  • "nodes": [
    ],
  • "read_bps": 0,
  • "read_eps": 0,
  • "row_count": 20,
  • "status": "Materialized view is not running on any node",
  • "status_code": 0,
  • "status_ts": 1737411240123,
  • "streaming_data_bytes": 12345,
  • "success_count": 99,
  • "throughput": [
    ],
  • "uptime": 60000,
  • "written_bps": 0,
  • "written_eps": 0
}

stop a sink

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

Authorizations:
BasicAuth
path Parameters
id
required
string

sink ID

Responses

Response samples

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

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:
BasicAuth
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:
BasicAuth

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:
BasicAuth
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": "string",
  • "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:
BasicAuth
path Parameters
id
required
string

source ID

Responses

Response samples

Content type
application/json
[
  • "string"
]

get a source

Get a source with the given ID.

Authorizations:
BasicAuth
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": "string",
  • "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"
}

patch a source

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

Authorizations:
BasicAuth
path Parameters
id
required
string

source ID

Request Body schema: application/json
required

patch source request parameters

description
string
name
string
object
stream
string

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": "string",
  • "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:
BasicAuth
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": "string",
  • "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"
}

get the logs of a source

Get the logs of a source with the given id.

Authorizations:
BasicAuth
path Parameters
id
required
string

source ID

query Parameters
lines
required
integer

number of lines

Responses

Response samples

Content type
application/json
[
  • "string"
]

start a source

Start the source with the given ID.

Authorizations:
BasicAuth
path Parameters
id
required
string

source ID

Responses

Response samples

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

get the stats of a source

Get the stats of a source with the given id.

Authorizations:
BasicAuth
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": [
    ],
  • "uptime": 60000
}

stop a source

Stop the source with the given ID.

Authorizations:
BasicAuth
path Parameters
id
required
string

source ID

Responses

Response samples

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

Streams v1beta2

list streams

Get all streams.

Authorizations:
BasicAuth
query Parameters
expand
boolean

whether the response should include optional metrics (row_count, streaming_data_bytes, historical_data_bytes) or not

db
string

database

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a stream

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

Authorizations:
BasicAuth
query Parameters
db
string

database

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",
  • "historical_data_bytes": 234567,
  • "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",
  • "row_count": 1000,
  • "secondary_indexes": [
    ],
  • "streaming_data_bytes": 12345,
  • "target_stream": "target",
  • "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:
BasicAuth
path Parameters
name
required
string

stream name

query Parameters
db
string

database

Responses

Response samples

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

get a stream

Get a stream with the given name.

Authorizations:
BasicAuth
path Parameters
name
required
string

stream name

query Parameters
db
string

database

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",
  • "historical_data_bytes": 234567,
  • "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",
  • "row_count": 1000,
  • "secondary_indexes": [
    ],
  • "streaming_data_bytes": 12345,
  • "target_stream": "target",
  • "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:
BasicAuth
path Parameters
name
required
string

name of the stream

query Parameters
db
string

database

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",
  • "historical_data_bytes": 234567,
  • "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",
  • "row_count": 1000,
  • "secondary_indexes": [
    ],
  • "streaming_data_bytes": 12345,
  • "target_stream": "target",
  • "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:
BasicAuth
path Parameters
name
required
string

stream name

query Parameters
db
string

database

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": "timeplusd"
}

get the stats of a stream

Get the stats of a stream with the given name.

Authorizations:
BasicAuth
path Parameters
name
required
string

stream name

query Parameters
db
string

database

historyDays
integer

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

granularity
string

granularity of the history metrics, default is 10m. Examples: [1m, 10m, 1h, 1d]

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
}

UDFs v1beta2

list user-defined functions

Get all user-defined functions.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create an user-defined function

Create an user-defined function.

Authorizations:
BasicAuth
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

Only valid when type is remote and auth_method is auth_header

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

description
string
is_aggregation
boolean

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

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",
  • "description": "my first UDF",
  • "is_aggregation": true,
  • "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",
  • "id": "string",
  • "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:
BasicAuth
path Parameters
name
required
string

user-defined function name

Responses

Response samples

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

get an user-defined function

get the user-defined function with the given name.

Authorizations:
BasicAuth
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",
  • "id": "string",
  • "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:
BasicAuth
path Parameters
name
required
string

user-defined function name

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

Only valid when type is remote and auth_method is auth_header

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

description
string
is_aggregation
boolean

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

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",
  • "description": "my first UDF",
  • "is_aggregation": true,
  • "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",
  • "id": "string",
  • "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:
BasicAuth
query Parameters
db
string

database

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:
BasicAuth
query Parameters
db
string

database

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

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",
  • "id": "string",
  • "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:
BasicAuth
path Parameters
name
required
string

view name

query Parameters
db
string

database

Responses

Response samples

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

get a view

Get a view with the given name.

Authorizations:
BasicAuth
path Parameters
name
required
string

view name

query Parameters
db
string

database

Responses

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "description for my_view",
  • "id": "string",
  • "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:
BasicAuth
path Parameters
name
required
string

name of the view

query Parameters
db
string

database

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": "timeplusd"
}

get the stats of a view

Get the stats of a view with the given name.

Authorizations:
BasicAuth
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": [
    ],
  • "lagging": 50,
  • "latest_event": "2023-02-13T07:08:09.012Z",
  • "memory": 1048576,
  • "nodes": [
    ],
  • "read_bps": 0,
  • "read_eps": 0,
  • "row_count": 20,
  • "status": "Materialized view is not running on any node",
  • "status_code": 0,
  • "status_ts": 1737411240123,
  • "streaming_data_bytes": 12345,
  • "written_bps": 0,
  • "written_eps": 0
}

Workspace v1beta2

get current workspace

Get the basic information about the current workspace.

Authorizations:
BasicAuth

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:
BasicAuth
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": "timeplusd"
}