API docs by Redocly

Timeplus Enterprise (v1)

Download OpenAPI specification:Download

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

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",
  • "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

exec request parameters

sql
required
string
timeout_ms
integer

default to 30000ms (30s)

type
required
string
Enum: "historical" "ddl"

Type of the sql

  • historical - a traditional sql that has limited results
  • ddl - a sql that is used to defining, altering, and deleting objects

Responses

Request samples

Content type
application/json
{
  • "sql": "string",
  • "timeout_ms": 5000,
  • "type": "historical"
}

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
type
string
Enum: "historical" "ddl" "streaming"

Responses

Request samples

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

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
[
  • {
    }
]

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": [
    ],
  • "create_query": "CREATE STREAM test_external_stream('str' string) ENGINE=ExternalStream SETTINGS type='kafka'",
  • "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"
}

preview an external stream

Preview an external stream. If the data format is JSONEachRow, the response event will be a JSON object. If it is other type such as Protobuf, the response event will only contain one raw field, which is the raw bytes of the event.

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
[
  • {
    }
]

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
{
  • "create_query": "CREATE EXTERNAL TABLE test_external_table SETTINGS type='mysql'",
  • "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
[
  • {
    }
]

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": [
    ],
  • "create_query": "CREATE MATERIALIZED VIEW my_view AS select * from car_live_data where speed_kmh > 100",
  • "created_at": "2023-02-01 23:22:59",
  • "created_by": {
    },
  • "description": "description for my_view",
  • "lagging": 50,
  • "last_error_message": "Materialized view is not running on any node",
  • "last_updated_at": "2023-02-05 11:12:13",
  • "last_updated_by": {
    },
  • "leader_node": 1,
  • "logstore_retention_bytes": 10737418240,
  • "logstore_retention_ms": 604800000,
  • "memory": 1048576,
  • "name": "my_view",
  • "query": "select * from car_live_data where speed_kmh > 100",
  • "status": "ExecutingPipeline",
  • "status_ts": 1737411240123,
  • "target_stream": "high_speed_cars",
  • "ttl_expression": "to_datetime(_tp_time) + INTERVAL 7 DAY"
}

pause a materialize view

Pause a materialize view.

Authorizations:
BasicAuth
query Parameters
db
string

database

sync
boolean

whether wait until the materialized view is fully paused

Responses

Response samples

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

recover a failed materialize view

Recover a failed materialize view.

Authorizations:
BasicAuth
query Parameters
db
string

database

Responses

Response samples

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

resume a materialize view

Resume a materialize view.

Authorizations:
BasicAuth
query Parameters
db
string

database

sync
boolean

whether wait until the materialized view is fully resumed

Responses

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

Responses

Response samples

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

transfer the leader of a shard of the materialize view

Transfer the leader of a shard of the materialize view.

Authorizations:
BasicAuth
query Parameters
db
string

database

sync
boolean

whether wait until the leader is fully transffered

Request Body schema: application/json
required

transfer leader request parameters

from
required
integer
shard
required
integer
to
required
integer

Responses

Request samples

Content type
application/json
{
  • "from": 1,
  • "shard": 1001,
  • "to": 3
}

Response samples

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

Pipelines v1beta2

parse ddl

parse ddl

Authorizations:
BasicAuth
Request Body schema: application/json
required

DDL to be parsed

string

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
{
  • "parsed": true,
  • "resourceDB": "string",
  • "resourceName": "string",
  • "resourceType": "string"
}

list pipelines

Get all pipelines.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

create a pipeline

Create a new pipeline with the given configuration.

Authorizations:
BasicAuth
Request Body schema: application/json
required

Pipeline configuration

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

Responses

Request samples

Content type
application/json
{
  • "description": "my pipeline",
  • "name": "my_pipeline",
  • "nodes_history": [
    ]
}

Response samples

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

delete a pipeline

Delete the pipeline with the given id.

Authorizations:
BasicAuth
path Parameters
id
required
string

pipeline id

Responses

Response samples

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

get a pipeline

Get a pipeline with the given name.

Authorizations:
BasicAuth
path Parameters
id
required
string

pipeline name

Responses

Response samples

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

append nodes to a pipeline

Append nodes to a pipeline

Authorizations:
BasicAuth
path Parameters
id
required
string

pipeline id

Request Body schema: application/json
required

nodes configuration

nodes
Array of any
update_time
string

Responses

Request samples

Content type
application/json
{
  • "nodes": [
    ],
  • "update_time": "2023-02-05 11:12:13"
}

Response samples

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

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
[
  • {
    }
]

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

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

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

stop a sink

Stop the sink with the given ID from sending out data. The underlying materialized view will be paused.

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. Some types of the stream doesn't have metrics. For example: MySQL, PostgreSQL and Iceberg

db
string

database

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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": [
    ],
  • "create_query": "CREATE STREAM test_stream('str' string) ENGINE=Stream(1,1,rand())",
  • "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,
  • "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

Responses

Response samples

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

UDFs v1beta2

list user-defined functions

Get all user-defined functions.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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": 1742240891590,
  • "created_by": "admin",
  • "description": "my first UDF",
  • "is_aggregation": true,
  • "last_modified_at": 1742240891590,
  • "last_modified_by": "admin",
  • "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
[
  • {
    }
]

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": [
    ],
  • "create_query": "CREATE VIEW my_view AS select * from car_live_data where speed_kmh > 100",
  • "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"
}

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