ByteHouse Public API (1.0.0)

Download OpenAPI specification:Download

The public ByteHouse API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Metadata

Make metadata subscription

Authorizations:

BearerAuth

header Parameters

X-Account-ID required	string Example: 2100042608 accountID for subscribing
X-User-ID required	string Example: 2100042608 user ID
X-Bytehouse-Token required	string Example: eyJhbGciOiJSUzI1Ni bytehouse token

Responses

Response samples

200
403
500

Content type

application/json

{"message": "Success"
}

Make metadata unsubscription

Authorizations:

BearerAuth

header Parameters

X-Account-ID required	string Example: 2100042608 accountID for subscribing
X-User-ID required	string Example: 2100042608 user ID
X-Bytehouse-Token required	string Example: eyJhbGciOiJSUzI1Ni bytehouse token

Responses

Response samples

200
403
500

Content type

application/json

{"message": "Success"
}

Databases

List databases

Authorizations:

BearerAuth

query Parameters

filter	string
offset	integer Example: offset=200 skip specified number of elements, offset shuold be >= 0
limit	integer Example: limit=100

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": [{"name": "db_name",
"type": "DATABASE",
"uuid": "0c3c217b-5a00-4e44-9538-328dac95625b",
"createdBy": {"id": 4780622283186922000,
"type": "VOLCANO_MAIN_ACCOUNT"
},
"createdAt": "2020-11-23T09:23:55.840932013Z"
}
],
"meta": {"offset": 4,
"total": 5
}
}

Create a database

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

name required	string Example: "db_name"
description	string Example: "testing database, please don't delete"

Responses

Request samples

Payload

Content type

application/json

{"name": "db_name",
"description": "testing database, please don't delete"
}

Response samples

201
403
500

Content type

application/json

{"data": {"uuid": "f9cac8f6-7bf0-4c37-bba1-5066356410a2"
}
}

Delete a database

Authorizations:

BearerAuth

path Parameters

db_name

required

string

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{ }

Retrieve a database

Authorizations:

BearerAuth

path Parameters

db_name

required

string

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": {"uuid": "sample_db_uuid",
"name": "my_db_name",
"description": "DB description entered by user with limit length.",
"noOfTables": 12,
"sizeInBytes": 212600881152,
"createdBy": {"id": 4780622283186922000,
"type": "VOLCANO_MAIN_ACCOUNT"
},
"createdAt": "2020-11-23T09:23:55.840932013Z",
"lastModifiedBy": {"id": 4780622283186922000,
"type": "VOLCANO_MAIN_ACCOUNT"
},
"lastModifiedAt": "2020-11-23T09:23:55.840932013Z",
"databaseType": "DATABASE"
}
}

List tables for a specified database

Authorizations:

BearerAuth

path Parameters

db_name

required

string

query Parameters

filter	string
offset	integer Example: offset=200 skip specified number of elements, offset shuold be >= 0
limit	integer Example: limit=100

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": [{"uuid": "sample_table_uuid",
"name": "performance",
"description": "sample description",
"tableType": "TABLE",
"createdBy": {"id": 4780622283186922000,
"type": "VOLCANO_MAIN_ACCOUNT"
},
"createdAt": "2020-11-23T09:23:55.840932013Z",
"lastModifiedAt": "2020-11-23T09:23:55.840932013Z"
}
],
"meta": {"offset": 4,
"total": 5
}
}

Create a table for a specified database

Authorizations:

BearerAuth

path Parameters

db_name

required

string

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

name required	string Example: "table_name" Name of the table.
description	string Example: "Hello Table" Description of the table.
required	Array of objects (Column) Example: [{"name":"ColumnID","type":"String","nullable":false,"defaultValue":"defaultValue","comment":"hello comment"},{"name":"ColumnDate","type":"Date","nullable":false,"defaultValue":"2019-01-01"},{"name":"ColumnHello","type":"int"},{"name":"ColumnNotNull","type":"String","nullable":false},{"name":"EventTime","type":"DateTime","defaultValue":"now()","isDefaultValueRawExpression":true}] List of columns of the table.
orderByKeys required	Array of strings Example: ["ColumnID","ColumnDate"] Name of the column whose values will be used to order the table's data. A key has to be one of the columns.
samplingKey	string Example: "ColumnID" SAMPLE BY expression. A key has to be one of the columns.
	Array of objects Example: [{"column":"ColumnDate","granularity":"day","expression":"toStartOfDay(`ColumnDate`)"},{"column":"ColumnNotNull","granularity":null,"expression":"ColumnNotNull"}] Keys to partition the table. A key has to be one of the columns.
primaryKeys	Array of strings Example: ["ColumnID","ColumnDate"] Primary keys of the table used as the main identifier of the rows. A key has to be one of the columns.
	object Table rows time-to-live (TTL) configuration.
	object Key used to guarantee uniqueness in the table. A key has to be one of the columns.
	object Bucket key. Modifiable after creation. A key has to be one of the columns.
	object Example: {"storage_dialect_type":"MYSQL","partition_level_unique_keys":0} Settings used for a table

Responses

Request samples

Payload

Content type

application/json

{"name": "table_name",
"description": "Hello Table",
"columns": [{"name": "ColumnID",
"type": "String",
"nullable": false,
"defaultValue": "defaultValue",
"comment": "hello comment"
},
{"name": "ColumnDate",
"type": "Date",
"nullable": false,
"defaultValue": "2019-01-01"
},
{"name": "ColumnHello",
"type": "int"
},
{"name": "ColumnNotNull",
"type": "String",
"nullable": false
},
{"name": "EventTime",
"type": "DateTime",
"defaultValue": "now()",
"isDefaultValueRawExpression": true
}
],
"orderByKeys": ["ColumnID",
"ColumnDate"
],
"samplingKey": "ColumnID",
"partitionKeys": [{"column": "ColumnDate",
"granularity": "day",
"expression": "toStartOfDay(`ColumnDate`)"
},
{"column": "ColumnNotNull",
"granularity": null,
"expression": "ColumnNotNull"
}
],
"primaryKeys": ["ColumnID",
"ColumnDate"
],
"ttl": {"column": "order_date",
"value": 3,
"unit": "MONTH",
"granularity": "hour",
"expression": "`toStartOfHour`(`order_date`) + INTERVAL 3 MONTH"
},
"uniqueKey": {"columns": ["ColumnID",
"ColumnDate"
],
"isUniqueTable": true,
"expression": "(`ColumnID`, `ColumnDate`)"
},
"clusterKey": {"columns": ["ColumnID",
"ColumnDate"
],
"numOfBuckets": 20,
"expression": "(`ColumnID`, `ColumnDate`)"
},
"settings": {"storage_dialect_type": "MYSQL",
"partition_level_unique_keys": 0
}
}

Response samples

201
403
500

Content type

application/json

{"data": {"uuid": "f9cac8f6-7bf0-4c37-bba1-5066356410a2"
}
}

List tables, views for a specified database

Authorizations:

BearerAuth

path Parameters

db_name

required

string

query Parameters

filter	string
offset	integer Example: offset=200 skip specified number of elements, offset shuold be >= 0
limit	integer Example: limit=100

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": [{"uuid": "sample_table_uuid",
"name": "performance",
"tableType": "TABLE",
"description": "sample description",
"createdBy": {"id": 4780622283186922000,
"type": "VOLCANO_MAIN_ACCOUNT"
},
"createdAt": "2020-11-23T09:23:55.840932013Z",
"lastModifiedAt": "2020-11-23T09:23:55.840932013Z"
}
],
"meta": {"offset": 4,
"total": 5
}
}

Get sync status for a materialized mysql database and all its underlying tables

Authorizations:

BearerAuth

path Parameters

db_name

required

string

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": {"dbSyncStatus": "Running",
"tableSyncStatus": [{"tableName": "materialized_mysql_table_1",
"status": "Running"
}
],
"lastException": "ConnectionFailed"
}
}

Delete a table

Authorizations:

BearerAuth

path Parameters

db_name required	string
table_name required	string

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{ }

Update a table

Authorizations:

BearerAuth

path Parameters

db_name required	string
table_name required	string

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

	Array of objects (Column) Example: [{"name":"ColumnID","type":"String","nullable":false,"defaultValue":"defaultValue","comment":"updated_column_comment"},{"name":"ColumnDate","type":"Date","nullable":false,"defaultValue":"2019-01-01"}]
dropColumns	Array of strings Example: ["dropColumn1","dropColumn2"]
	Array of objects (Column) Example: [{"name":"ColumnExisting","type":"String","defaultValue":"defaultValue","comment":"you can update data type (including Nullable), default value and comment when modifying columns"},{"name":"ColumnExisting2","type":"Date","nullable":false,"defaultValue":"2019-01-01"}]
	Array of objects
	object Table TTL (time to live) for rows - set a new interval for the table TTL
isRemoveTTL	boolean Example: false

Responses

Request samples

Payload

Content type

application/json

{"addColumns": [{"name": "ColumnID",
"type": "String",
"nullable": false,
"defaultValue": "defaultValue",
"comment": "updated_column_comment"
},
{"name": "ColumnDate",
"type": "Date",
"nullable": false,
"defaultValue": "2019-01-01"
}
],
"dropColumns": ["dropColumn1",
"dropColumn2"
],
"modifyColumns": [{"name": "ColumnExisting",
"type": "String",
"defaultValue": "defaultValue",
"comment": "you can update data type (including Nullable), default value and comment when modifying columns"
},
{"name": "ColumnExisting2",
"type": "Date",
"nullable": false,
"defaultValue": "2019-01-01"
}
],
"renameColumns": [{"fromName": "old_column_name",
"toName": "new_column_name"
}
],
"ttl": {"column": "order_date",
"value": 3,
"unit": "MONTH",
"granularity": "hour"
},
"isRemoveTTL": false
}

Response samples

200
403
500

Content type

application/json

{ }

Retrieve a table

Authorizations:

BearerAuth

path Parameters

db_name required	string
table_name required	string

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": {"uuid": "a637ce52-07ca-4e80-b05a-458c42ab2f72",
"sizeInBytes": 13011000000000,
"noOfRows": 34567890,
"createdBy": {"id": 4780622283186922000,
"type": "VOLCANO_MAIN_ACCOUNT"
},
"createdAt": "2020-11-23T09:23:55.840932013Z",
"lastModifiedAt": "2020-11-23T09:23:55.840932013Z",
"name": "table_name",
"description": "Hello Table",
"orderByKeys": ["ColumnID",
"ColumnDate"
],
"samplingKey": "ColumnID",
"partitionKeys": [{"column": "ColumnDate",
"granularity": "day",
"expression": "toStartOfDay(`ColumnDate`)"
},
{"column": "ColumnNotNull",
"granularity": null,
"expression": "ColumnNotNull"
}
],
"primaryKeys": ["ColumnID",
"ColumnDate"
],
"ttl": {"column": "order_date",
"value": 3,
"unit": "MONTH",
"granularity": "hour",
"expression": "`toStartOfHour`(`order_date`) + INTERVAL 3 MONTH"
},
"uniqueKey": {"columns": ["ColumnID",
"ColumnDate"
],
"isUniqueTable": true,
"expression": "(`ColumnID`, `ColumnDate`)"
},
"clusterKey": {"columns": ["ColumnID",
"ColumnDate"
],
"numOfBuckets": 20,
"expression": "(`ColumnID`, `ColumnDate`)"
},
"tableType": "TABLE",
"columns": [{"uuid": "f965ac8f6-7bf0-4c37-bba1-5066353410a4",
"name": "ColumnID",
"type": "String",
"nullable": false,
"defaultValue": "defaultValue",
"queryFrequency": 1000,
"queryCount": 243242,
"comment": "hello comment",
"lastQueryTime": "2020-11-23T09:23:55.840932013Z",
"fullColumnExpression": "String"
},
{"uuid": "f965ac8f6-7bf0-4c37-bba1-5066353410a5",
"name": "ColumnDate",
"type": "Date",
"nullable": false,
"defaultValue": "2019-01-01",
"queryFrequency": 898,
"queryCount": 24324,
"lastQueryTime": null,
"fullColumnExpression": "Date"
},
{"uuid": "f965ac8f6-7bf0-4c37-bba1-5066353410a6",
"name": "ColumnHello",
"type": "Int",
"nullable": true,
"queryFrequency": 500,
"queryCount": 2432,
"lastQueryTime": "2020-11-23T09:23:55.840932013Z",
"fullColumnExpression": "Nullable(Int)"
},
{"uuid": "f965ac8f6-7bf0-4c37-bba1-5066353410a7",
"name": "ColumnNotNull",
"type": "String",
"nullable": false,
"queryFrequency": 100,
"queryCount": 243,
"lastQueryTime": "2020-11-23T09:23:55.840932013Z",
"fullColumnExpression": "String"
},
{"uuid": "f965ac8f6-7bf0-4c37-bba1-5066353410a4",
"name": "ColumnBitEngine",
"type": "BitMap64",
"nullable": false,
"queryFrequency": 100,
"queryCount": 243,
"lastQueryTime": "2020-11-23T09:23:55.840932013Z",
"fullColumnExpression": "Nullable(BitMap64)",
"encoding_expression": "BitEngineEncode"
}
]
}
}

Retrieve the partitions for a specified table

Authorizations:

BearerAuth

path Parameters

db_name required	string
table_name required	string

query Parameters

limit	integer Example: limit=100
offset	integer Example: offset=200 skip specified number of elements, offset shuold be >= 0
filter	string

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": [{"partitionName": "partition 1",
"sizeInBytes": 300,
"rowCount": 3000,
"lastModifiedAt": "2020-11-23T09:23:55.840932013Z"
}
],
"meta": {"offset": 4,
"total": 5
}
}

Delete partitions for a specified table

Authorizations:

BearerAuth

path Parameters

db_name required	string
table_name required	string

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

partitionNames

Array of strings

Example: ["partition_name1"]

Responses

Request samples

Payload

Content type

application/json

{"partitionNames": ["partition_name1"
]
}

Response samples

200

Content type

application/json

{"data": "Success"
}

Retrieves the min and max partition names in alphabet-numerical order for a specified table

Authorizations:

BearerAuth

path Parameters

db_name required	string
table_name required	string

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": {"maxPartitionName": "`2022-07-31`",
"minPartitionName": "`2022-07-01`"
}
}

List materialized views for a specified database

Authorizations:

BearerAuth

path Parameters

db_name

required

string

query Parameters

filter	string
offset	integer Example: offset=200 skip specified number of elements, offset shuold be >= 0
limit	integer Example: limit=100

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": [{"uuid": "sample_mv_uuid",
"name": "performance",
"description": "sample description",
"tableType": "MATERIALIZED-VIEW",
"baseDatabase": "base",
"baseTable": "table",
"targetDatabase": "target",
"targetTable": "table",
"ratio": 124.1,
"hitTimes": 100,
"createdBy": {"id": 4780622283186922000,
"type": "VOLCANO_MAIN_ACCOUNT"
},
"createdAt": "2020-11-23T09:23:55.840932013Z",
"lastModifiedAt": "2020-11-23T09:23:55.840932013Z"
}
],
"meta": {"offset": 4,
"total": 5
}
}

Retrieve a materialized view

Authorizations:

BearerAuth

path Parameters

db_name required	string
mv_name required	string

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": {"uuid": "a637ce52-07ca-4e80-b05a-458c42ab2f72",
"baseDatabase": "base",
"baseTable": "table",
"targetDatabase": "target",
"targetTable": "table",
"ratio": 124.1,
"hitTimes": 100,
"createdBy": {"id": 4780622283186922000,
"type": "VOLCANO_MAIN_ACCOUNT"
},
"createdAt": "2020-11-23T09:23:55.840932013Z",
"lastModifiedAt": "2020-11-23T09:23:55.840932013Z",
"name": "table_name",
"description": "Hello Table",
"orderByKeys": ["ColumnID",
"ColumnDate"
],
"samplingKey": "ColumnID",
"partitionKeys": [{"column": "ColumnDate",
"granularity": "day",
"expression": "toStartOfDay(`ColumnDate`)"
},
{"column": "ColumnNotNull",
"granularity": null,
"expression": "ColumnNotNull"
}
],
"primaryKeys": ["ColumnID",
"ColumnDate"
],
"ttl": {"column": "order_date",
"value": 3,
"unit": "MONTH",
"granularity": "hour",
"expression": "`toStartOfHour`(`order_date`) + INTERVAL 3 MONTH"
},
"uniqueKey": {"columns": ["ColumnID",
"ColumnDate"
],
"isUniqueTable": true,
"expression": "(`ColumnID`, `ColumnDate`)"
},
"clusterKey": {"columns": ["ColumnID",
"ColumnDate"
],
"numOfBuckets": 20,
"expression": "(`ColumnID`, `ColumnDate`)"
},
"tableType": "TABLE",
"columns": [{"uuid": "f965ac8f6-7bf0-4c37-bba1-5066353410a4",
"name": "ColumnID",
"type": "String",
"nullable": false,
"defaultValue": "defaultValue",
"queryFrequency": 1000,
"queryCount": 243242,
"comment": "hello comment",
"lastQueryTime": "2020-11-23T09:23:55.840932013Z",
"fullColumnExpression": "String"
},
{"uuid": "f965ac8f6-7bf0-4c37-bba1-5066353410a5",
"name": "ColumnDate",
"type": "Date",
"nullable": false,
"defaultValue": "2019-01-01",
"queryFrequency": 898,
"queryCount": 24324,
"lastQueryTime": null,
"fullColumnExpression": "Date"
},
{"uuid": "f965ac8f6-7bf0-4c37-bba1-5066353410a6",
"name": "ColumnHello",
"type": "Int",
"nullable": true,
"queryFrequency": 500,
"queryCount": 2432,
"lastQueryTime": "2020-11-23T09:23:55.840932013Z",
"fullColumnExpression": "Nullable(Int)"
},
{"uuid": "f965ac8f6-7bf0-4c37-bba1-5066353410a7",
"name": "ColumnNotNull",
"type": "String",
"nullable": false,
"queryFrequency": 100,
"queryCount": 243,
"lastQueryTime": "2020-11-23T09:23:55.840932013Z",
"fullColumnExpression": "String"
},
{"uuid": "f965ac8f6-7bf0-4c37-bba1-5066353410a4",
"name": "ColumnBitEngine",
"type": "BitMap64",
"nullable": false,
"queryFrequency": 100,
"queryCount": 243,
"lastQueryTime": "2020-11-23T09:23:55.840932013Z",
"fullColumnExpression": "Nullable(BitMap64)",
"encoding_expression": "BitEngineEncode"
}
]
}
}

Delete a dictionary

Authorizations:

BearerAuth

path Parameters

db_name required	string
dict_name required	string

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{ }

Cluster Status

Retrieve cluster status of a particular table to provision its bucketing progress

Authorizations:

BearerAuth

path Parameters

db_name required	string
table_name required	string

Responses

Response samples

200
403
500

Content type

application/json

{"data": {"status": [1
]
},
"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
}
}

Queries-V2

Clickhouse HTTP Interface with a different hostname

Authorizations:

BearerAuth

query Parameters

virtual_warehouse	string virtual warehouse to be used for the query
query	string query to be ran
user	string Example: user=bytehouse bytehouse
password	string api-key

header Parameters

X-ClickHouse-User required	string Example: Bytehouse
X-ClickHouse-Key required	string Example: your-api-key

Responses

Clickhouse HTTP Interface with a different hostname

Authorizations:

BearerAuth

query Parameters

virtual_warehouse	string virtual warehouse to be used for the query
query	string query to be ran
user	string Example: user=bytehouse bytehouse
password	string api-key

header Parameters

X-ClickHouse-User required	string Example: Bytehouse
X-ClickHouse-Key required	string Example: your-api-key

Responses

Response samples

403
500

Content type

application/json

{"error": {"message": "user 12345 does not have permission to resource with identifier 0c3c217b-5a00-4e44-9538-328dac95625b"
}
}

Submit a synchronous query with a different hostname limited to first 1000 rows.

Authorizations:

BearerAuth

Request Body schema: application/json

query required	string Example: "USE TUTORIAL_DB; SELECT * FROM TUTORIAL_DB.Customer;"
mode required	string Enum: "ansi_sql" "clickhouse_sql"
vwID	string Example: "vw-compute-wh-test-8839992783"
queryID	string Example: "optional-1234567891011121314151617181920s211a22231"

Responses

Request samples

Payload

Content type

application/json

{"query": "USE TUTORIAL_DB; SELECT * FROM TUTORIAL_DB.Customer;",
"mode": "ansi_sql",
"vwID": "vw-compute-wh-test-8839992783",
"queryID": "optional-1234567891011121314151617181920s211a22231"
}

Response samples

200
403

Content type

application/json

{"meta": [{"name": "string",
"type": "string"
}
],
"data": [["string"
]
],
"rows": 0,
"statistics": {"elapsed": 0,
"rows_read": 0,
"bytes_read": 0
}
}

Submit a asynchronous query with a different hostname

Authorizations:

BearerAuth

Request Body schema: application/json

query required	string Example: "USE TUTORIAL_DB; SELECT * FROM TUTORIAL_DB.Customer;"
mode required	string Enum: "ansi_sql" "clickhouse_sql"
vwID	string Example: "vw-compute-wh-test-8839992783"
queryID	string Example: "optional-1234567891011121314151617181920s211a22231"

Responses

Request samples

Payload

Content type

application/json

{"query": "USE TUTORIAL_DB; SELECT * FROM TUTORIAL_DB.Customer;",
"mode": "ansi_sql",
"vwID": "vw-compute-wh-test-8839992783",
"queryID": "optional-1234567891011121314151617181920s211a22231"
}

Response samples

200

Content type

application/json

{"data": [{"status": "running",
"queryID": "query-id-one-two-three",
"errorMessage": "Code 100 DB Exception: Unknown Table `fakeDB.fakeTable`"
}
]
}

Retrieve the status for a specified asynchronous query

Authorizations:

BearerAuth

path Parameters

id

required

string

Example: b36fa16e-a0ce-4274-a744-621357180928

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"data": {"state": "running",
"errorMessage": "internal error",
"sqlStatement": "SELECT 1",
"startTime": "2020-11-23T09:23:55.840932013Z",
"endTime": "2020-11-23T09:23:55.840932013Z"
}
}

Retrieve the results for a specified asynchronous query

Authorizations:

BearerAuth

path Parameters

id

required

string

Example: b36fa16e-a0ce-4274-a744-621357180928

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": {"meta": [{"name": "string",
"type": "string"
}
],
"data": [["string"
]
],
"rows": 0,
"statistics": {"elapsed": 0,
"rows_read": 0,
"bytes_read": 0
}
}
}

Queries

Submit a synchronous query Deprecated

Authorizations:

BearerAuth

header Parameters

X-QuerySession-ID	string Query/Worksheet session ID
X-User-ActiveRole	string Example: AccountAdmin User Active Role

Request Body schema: application/json

query required	string Example: "USE TUTORIAL_DB; SELECT * FROM TUTORIAL_DB.Customer;"
mode required	string Enum: "ansi_sql" "clickhouse_sql"
vwID	string Example: "vw-compute-wh-test-8839992783"
queryID	string Example: "optional-1234567891011121314151617181920s211a22231"
asyncModeSwitchAfterInSec	integer Example: 0
maxRowsReturn	integer Example: 2 maximum number of rows return in the result (0 means return all rows)
insertWithData	boolean Example: false sends all the data in a single pass for insert queries

Responses

Request samples

Payload

Content type

application/json

{"query": "USE TUTORIAL_DB; SELECT * FROM TUTORIAL_DB.Customer;",
"mode": "ansi_sql",
"vwID": "vw-compute-wh-test-8839992783",
"queryID": "optional-1234567891011121314151617181920s211a22231",
"asyncModeSwitchAfterInSec": 0,
"maxRowsReturn": 2,
"insertWithData": false
}

Response samples

200
403
500

Content type

application/json

{"data": [{"sessionID": "08c2cf17-b4e4-43b7-a93f-6012e5d63ff8",
"queryID": "08c2cf17-b4e4-43b7-a93f-6012e5d63ff8",
"sqlStatement": "SELECT *\nFROM `test_db`.`test_table`\nLIMIT 1000",
"executionType": "QUERY",
"status": "SUCCESS",
"startTime": "2020-11-23T09:23:55.840932013Z",
"endTime": "2020-11-23T09:23:55.840932013Z",
"durationInMs": 3050,
"vwResumeDurationInMs": 3000,
"errorMessage": "Code 100 DB Exception: Unknown Table `fakeDB.fakeTable`",
"rowsNum": 100,
"columns": [{"name": "ColumnID",
"type": "String",
"nullable": false,
"defaultValue": "defaultValue"
},
{"name": "ColumnDate",
"type": "Date",
"nullable": false,
"defaultValue": "2019-01-01"
}
],
"rows": [["123456",
"Linus Torvald",
"Principal Developer, Linux Kernel",
"March 21 1990"
],
["123456",
"Rob Pike",
"Google Cloud Leading Director",
"Jan 23 1996"
]
]
}
]
}

Abort a synchronous query Deprecated

Authorizations:

BearerAuth

header Parameters

X-QuerySession-ID	string Query/Worksheet session ID
X-User-ActiveRole	string Example: AccountAdmin User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": {"killed": true
}
}

Kill a sync query Deprecated

Authorizations:

BearerAuth

path Parameters

id

required

string

Example: b36fa16e-a0ce-4274-a744-621357180928

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": {"killed": true
}
}

Submit an asynchronous query Deprecated

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

query required	string Example: "USE TUTORIAL_DB; SELECT * FROM TUTORIAL_DB.Customer;"
mode required	string Enum: "ansi_sql" "clickhouse_sql"
vwID	string Example: "vw-compute-wh-test-8839992783"
queryID	string Example: "optional-1234567891011121314151617181920s211a22231"

Responses

Request samples

Payload

Content type

application/json

{"query": "USE TUTORIAL_DB; SELECT * FROM TUTORIAL_DB.Customer;",
"mode": "ansi_sql",
"vwID": "vw-compute-wh-test-8839992783",
"queryID": "optional-1234567891011121314151617181920s211a22231"
}

Response samples

200
403
500

Content type

application/json

{"data": [{"status": "running",
"queryID": "query-id-one-two-three",
"Exception": "Code 100 DB Exception: Unknown Table `fakeDB.fakeTable`"
}
]
}

Kill a query Deprecated

Authorizations:

BearerAuth

path Parameters

id

required

string

Example: b36fa16e-a0ce-4274-a744-621357180928

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": {"killed": true
}
}

Retrieve the status for a specified asynchronous query Deprecated

Authorizations:

BearerAuth

path Parameters

id

required

string

Example: b36fa16e-a0ce-4274-a744-621357180928

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"data": {"state": "running",
"errorMessage": "internal error",
"sqlStatement": "SELECT 1",
"startTime": "2020-11-23T09:23:55.840932013Z",
"endTime": "2020-11-23T09:23:55.840932013Z"
}
}

Retrieve the results for a specified asynchronous query Deprecated

Authorizations:

BearerAuth

path Parameters

id

required

string

Example: b36fa16e-a0ce-4274-a744-621357180928

query Parameters

maxRowsReturn

integer

Example: maxRowsReturn=2

maximum rows return in the result(0 means return all rows)

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": [{"sessionID": "08c2cf17-b4e4-43b7-a93f-6012e5d63ff8",
"queryID": "08c2cf17-b4e4-43b7-a93f-6012e5d63ff8",
"sqlStatement": "SELECT *\nFROM `test_db`.`test_table`\nLIMIT 1000",
"executionType": "QUERY",
"status": "SUCCESS",
"startTime": "2020-11-23T09:23:55.840932013Z",
"endTime": "2020-11-23T09:23:55.840932013Z",
"durationInMs": 3050,
"vwResumeDurationInMs": 3000,
"errorMessage": "Code 100 DB Exception: Unknown Table `fakeDB.fakeTable`",
"rowsNum": 100,
"columns": [{"name": "ColumnID",
"type": "String",
"nullable": false,
"defaultValue": "defaultValue"
},
{"name": "ColumnDate",
"type": "Date",
"nullable": false,
"defaultValue": "2019-01-01"
}
],
"rows": [["123456",
"Linus Torvald",
"Principal Developer, Linux Kernel",
"March 21 1990"
],
["123456",
"Rob Pike",
"Google Cloud Leading Director",
"Jan 23 1996"
]
]
}
]
}

check tables, views and materialized views queried for query

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

query	string Example: "USE TUTORIAL_DB; SELECT * FROM TUTORIAL_DB.Customer;"
	object (UserInfo)

Responses

Request samples

Payload

Content type

application/json

{"query": "USE TUTORIAL_DB; SELECT * FROM TUTORIAL_DB.Customer;",
"userInfo": {"accountID": 112233,
"userID": 112233,
"activeRole": "AccountAdmin"
}
}

Response samples

200
500

Content type

application/json

{"data": {"valid": true,
"message": "access denied, user has not access to table1 ",
"tables": ["databaseName.table1",
"databaseName.table2"
]
}
}

Retrieve dialects available for a user

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
403
500

Content type

application/json

{"data": ["clickhouse",
"ansi",
"mysql"
]
}

Documentation

List all sql functions available to Bytehouse

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
400
403

Content type

application/json; charset=utf-8

{"data": [{"name": "any",
"type": "aggregate",
"description": "Selects the first encountered value.",
"example": "SELECT any(number) FROM numbers(10);",
"class": ""
}
]
}

Authentication

Create API key

Create a new API key for current user. The number of API key is limited to 2 per user. Use API key in header Authorization: Bearer for authentication.

Authorizations:

BearerAuth

Request Body schema: application/json

noExpiry	boolean Example: false Defines whether the API key has an expiry time or not. If set to true, `expiryInDays` will be ignored.
expiryInDays	integer Example: 90 Defines the expiry time (in days) of the created API key starting from time of creation.
comment	string API key description / comment.

Responses

Request samples

Payload

Content type

application/json

{"noExpiry": false,
"expiryInDays": 90,
"comment": "string"
}

Response samples

201
400

Content type

application/json

{"data": {"id": "8914859996411850157",
"key": "qUNomoCoqSokljuoRs5z",
"status": "ENABLED",
"noExpiry": false,
"expiredAt": "2020-11-23T09:23:55.840932013Z",
"createdAt": "2020-11-23T09:23:55.840932013Z",
"updatedAt": "2020-11-23T09:23:55.840932013Z",
"comment": "string"
}
}

List user API keys

Listing all of the current user's API key(s).

Authorizations:

BearerAuth

Responses

Response samples

200

Content type

application/json

{"data": [{"id": "8914859996411850157",
"maskedKey": "qUNomoCoqS**********",
"status": "ENABLED",
"expiredAt": "2020-11-23T09:23:55.840932013Z",
"createdAt": "2020-11-23T09:23:55.840932013Z",
"updatedAt": "2020-11-23T09:23:55.840932013Z",
"noExpiry": false,
"comment": "string",
"accountID": 0
}
]
}

Delete API key

Delete self-owned API key.

Authorizations:

BearerAuth

path Parameters

api_key_id

required

integer

Example: 1

ID of User's API Key

Responses

Response samples

200
403
404

Content type

application/json; charset=utf-8

{"message": "Success"
}

Enable or disable API Key

Update the status of the API key.

Authorizations:

BearerAuth

path Parameters

api_key_id

required

integer

Example: 1

ID of User's API Key

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

status

string (ApiKeyStatus)

Enum: "ENABLED" "DISABLED"

Example: "ENABLED"

API key status

Responses

Request samples

Payload

Content type

application/json

{"status": "ENABLED"
}

Response samples

200
403
404

Content type

application/json; charset=utf-8

{"message": "Success"
}

Extend API key expiry time

Extends the expiry date of an API key, this is a no-op when given a non-expiring API key.

Authorizations:

BearerAuth

path Parameters

api_key_id

required

integer

Example: 1

ID of User's API Key

Request Body schema: application/json

addExpiryInDays

integer

Example: 90

Number of days to add on to the expiry.

Responses

Request samples

Payload

Content type

application/json

{"addExpiryInDays": 90
}

Response samples

200
403
404

Content type

application/json; charset=utf-8

{"message": "Success"
}

Authorization

List resource actions

List the available action enums on given resources. Only the resource type matters.

Authorizations:

BearerAuth

Request Body schema: application/json; charset=utf-8

resources

Array of strings (BRNResource)

List of resources to list the actions of. Only the type matters in this call.

Responses

Request samples

Payload

Content type

application/json; charset=utf-8

{"resources": ["string"
]
}

Response samples

200
400

Content type

application/json; charset=utf-8

{"data": {"resource_actions": [{"resource": "string",
"actions": ["CREATE"
]
}
]
}
}

Check privileges

Check if operator is authorized to perform actions

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json; charset=utf-8

Array of objects (PrivilegeCheck)

List of action(s) on resource(s) to check.

Array

resource	string (BRNResource) Resource in BRN format (brn:[accountID]:[region]:[resource]). Examples: brn:123456789:cn-beijing:data/database:my_db/table:my_table brn:123456789:cn-beijing:data/database:my_db/* brn:123456789:cn-beijing:data/database:my_db brn:123456789:cn-beijing:data/* brn:123456789:cn-beijing:warehouse:my_vw brn:123456789:cn-beijing:job:my_job
action	string (ResourceAction) Enum: "CREATE" "ALTER" "DROP" "SHOW" "SELECT" "INSERT" "OPTIMIZE" "TRUNCATE" "GET" "EXECUTE" Resource action, enums depend on the type of the resource. See "List resource actions".
grant_option	boolean Set to `true` to check if the user can grant the privilege to others.

Responses

Request samples

Payload

Content type

application/json; charset=utf-8

{"privileges": [{"resource": "string",
"action": "CREATE",
"grant_option": true
}
]
}

Response samples

200
400

Content type

application/json; charset=utf-8

{"allowed": [{"resource": "string",
"action": "CREATE",
"grant_option": true
}
],
"denied": [{"resource": "string",
"action": "CREATE",
"grant_option": true
}
]
}

Grant privileges

Grant privileges over a resource to a principal. The operator must have grant capabilities.

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json; charset=utf-8

resource required	string (BRNResource) Resource in BRN format (brn:[accountID]:[region]:[resource]). Examples: brn:123456789:cn-beijing:data/database:my_db/table:my_table brn:123456789:cn-beijing:data/database:my_db/* brn:123456789:cn-beijing:data/database:my_db brn:123456789:cn-beijing:data/* brn:123456789:cn-beijing:warehouse:my_vw brn:123456789:cn-beijing:job:my_job
required	object (Principal) Principal containing the principal type and ID
actions required	Array of strings (ResourceAction) Items Enum: "CREATE" "ALTER" "DROP" "SHOW" "SELECT" "INSERT" "OPTIMIZE" "TRUNCATE" "GET" "EXECUTE" Actions to be granted on the resource. See "List resource actions".
grant_option	boolean Allow the user or role to grant this privilege to another.

Responses

Request samples

Payload

Content type

application/json; charset=utf-8

{"resource": "string",
"principal": {"type": "USER",
"id": "string"
},
"actions": ["CREATE"
],
"grant_option": true
}

Response samples

200
400
403

Content type

application/json; charset=utf-8

{"message": "Success"
}

Revoke privileges

Revoke privileges over a resource from a principal.

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json; charset=utf-8

resource required	string (BRNResource) Resource in BRN format (brn:[accountID]:[region]:[resource]). Examples: brn:123456789:cn-beijing:data/database:my_db/table:my_table brn:123456789:cn-beijing:data/database:my_db/* brn:123456789:cn-beijing:data/database:my_db brn:123456789:cn-beijing:data/* brn:123456789:cn-beijing:warehouse:my_vw brn:123456789:cn-beijing:job:my_job
required	object (Principal) Principal containing the principal type and ID
actions required	Array of strings (ResourceAction) Items Enum: "CREATE" "ALTER" "DROP" "SHOW" "SELECT" "INSERT" "OPTIMIZE" "TRUNCATE" "GET" "EXECUTE" Actions to be revoked on the resource. See "List resource actions".

Responses

Request samples

Payload

Content type

application/json; charset=utf-8

{"resource": "string",
"principal": {"type": "USER",
"id": "string"
},
"actions": ["CREATE"
]
}

Response samples

200
400
403

Content type

application/json; charset=utf-8

{"message": "Success"
}

List principal privileges

List privileges granted to a principal.

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json; charset=utf-8

	object (Principal) Principal containing the principal type and ID
resources	Array of strings Example: ["brn:123456789:cn-beijing:data/database:my_db/table:my_table"] List of resources to list the privileges of.

Responses

Request samples

Payload

Content type

application/json; charset=utf-8

{"principal": {"type": "USER",
"id": "string"
},
"resources": ["brn:123456789:cn-beijing:data/database:my_db/table:my_table"
]
}

Response samples

200
400

Content type

application/json; charset=utf-8

{"data": {"privileges": [{"resource": "string",
"actions": [{"action": "SHOW",
"grant": true,
"mutable": true
}
]
}
]
}
}

List privileges grouped by (principal,resource)

List privileges grouped by (principal,resource).

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json; charset=utf-8

resources

Array of strings

Example: ["brn:123456789:cn-beijing:data/database:my_db/table:my_table"]

List of resources to list the privileges of.

Responses

Request samples

Payload

Content type

application/json; charset=utf-8

{"resources": ["brn:123456789:cn-beijing:data/database:my_db/table:my_table"
]
}

Response samples

200
400

Content type

application/json; charset=utf-8

{"data": {"principals": [{"principal": {"type": "USER",
"id": "string"
},
"privileges": [{"resource": "string",
"actions": [{"action": "SHOW",
"grant": true,
"mutable": true
}
]
}
]
}
]
}
}

List privileges grouped by (resource,principal)

List privileges grouped by (resource,principal).

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json; charset=utf-8

Array of objects (PrivilegeGrant)

List of resources to list the privileges of.

Array

resource	string (BRNResource) Resource in BRN format (brn:[accountID]:[region]:[resource]). Examples: brn:123456789:cn-beijing:data/database:my_db/table:my_table brn:123456789:cn-beijing:data/database:my_db/* brn:123456789:cn-beijing:data/database:my_db brn:123456789:cn-beijing:data/* brn:123456789:cn-beijing:warehouse:my_vw brn:123456789:cn-beijing:job:my_job
actions	Array of strings Actions to grant/revoke on/from the resource.
grant_option	boolean Set to `true` to check if the user can grant the privilege to others.

Responses

Request samples

Payload

Content type

application/json; charset=utf-8

{"privileges": [{"resource": "string",
"actions": ["string"
],
"grant_option": true
}
]
}

Response samples

200
400

Content type

application/json; charset=utf-8

{"data": {"privileges": [{"resource": "string",
"principals": [{"principal": {"type": "USER",
"id": "string"
},
"actions": [{"action": "SHOW",
"grant": true,
"mutable": true
}
]
}
]
}
]
}
}

Roles and Assignments

List all roles

List all role names.

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
400
403

Content type

application/json; charset=utf-8

["my_new_role"
]

Create role

Creates a new role, this will be a no-op operation if given a role that already exists.

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json; charset=utf-8

name required	string Example: "my_new_role" Name of the role. This will be the main identifier of the role.
description	string Description of the role

Responses

Request samples

Payload

Content type

application/json; charset=utf-8

{"name": "my_new_role",
"description": "string"
}

Response samples

200
400
403

Content type

application/json; charset=utf-8

{"message": "Success"
}

Delete role

Deletes an existing role.

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json; charset=utf-8

name

required

string

Example: "my_new_role"

Name of the role to delete

Responses

Request samples

Payload

Content type

application/json; charset=utf-8

{"name": "my_new_role"
}

Response samples

200
400
403
404

Content type

application/json; charset=utf-8

{"message": "Success"
}

Get a role

Get a role information.

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json; charset=utf-8

name

required

string

Example: "my_new_role"

Name of the role

Responses

Request samples

Payload

Content type

application/json; charset=utf-8

{"name": "my_new_role"
}

Response samples

200
400
403
404

Content type

application/json; charset=utf-8

{"name": "my_new_role",
"description": "My new role",
"created_at": "2024-07-16T10:25:39.144Z"
}

Assign role

Assign a role to a user.

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json; charset=utf-8

role_name required	string Example: "my_new_role" Name of the role to assign
user_id required	integer Example: 123 User ID to assign the role to

Responses

Request samples

Payload

Content type

application/json; charset=utf-8

{"role_name": "my_new_role",
"user_id": 123
}

Response samples

200
400
403
404

Content type

application/json; charset=utf-8

{"message": "Success"
}

Unassign role

Unassign a role from a user.

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json; charset=utf-8

role_name required	string Example: "my_new_role" Name of the role to unassign
user_id required	integer Example: 123 User ID to unassign the role from

Responses

Request samples

Payload

Content type

application/json; charset=utf-8

{"role_name": "my_new_role",
"user_id": 123
}

Response samples

200
400
403
404

Content type

application/json; charset=utf-8

{"message": "Success"
}

List role assignments

List existing role assignments.

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json; charset=utf-8

role_names	Array of strings Example: ["my_role","my_new_role"] Optional role names filter
user_ids	Array of integers Example: [123,456] Optional user IDs filter

Responses

Request samples

Payload

Content type

application/json; charset=utf-8

{"role_names": ["my_role",
"my_new_role"
],
"user_ids": [123,
456
]
}

Response samples

200

Content type

application/json; charset=utf-8

{"data": {"assignments": [{"role_name": "my_new_role",
"user_id": 123
}
]
}
}

Usage

Retrieve the storage utilisation for a specified timeframe

Authorizations:

BearerAuth

query Parameters

startTime required	string Example: startTime=2021-11-23T09:23:55.840932013Z stats start time
endTime required	string Example: endTime=2021-11-24T09:23:55.840932013Z stats end time
dbName	string Example: dbName=dbName db name

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
},
"data": {"granularity": 3600,
"series": [{"date": "2020-11-23T09:23:55.840932013Z",
"totalSizeInBytes": 234,
"totalRows": 234,
"details": [{"dbName": "dbName1",
"sizeInBytes": 2342,
"rows": 2342
}
]
}
]
}
}

Retrieve the virtual warehouse utilisation for a specified timeframe

Authorizations:

BearerAuth

query Parameters

startTime required	string Example: startTime=2021-11-23T09:23:55.840932013Z stats start time
endTime required	string Example: endTime=2021-11-24T09:23:55.840932013Z stats end time
vwName	string Example: vwName=vwName vw name

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
},
"data": {"granularity": 3600,
"series": [{"date": "2020-11-23T09:23:55.840932013Z",
"totalCredits": 234.1,
"details": [{"vwName": "vwName1",
"credit": 20.24
}
]
}
]
}
}

Statistics

Retrieve a query statistic

Authorizations:

BearerAuth

path Parameters

id

required

string

Example: b36fa16e-a0ce-4274-a744-621357180928

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
},
"data": {"elapsed": 1,
"rows_read": 100,
"bytes_read": 100,
"total_cpu_seconds": 0.1,
"io_wait_seconds": 0.1
}
}

Data Loading

Create a connection

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

name required	string (ConnectionName) Example: "s3_sales_report" A descriptive name for your connection, 128 chars or less
type required	string (ImportSourceType) Enum: "LOCAL" "S3" "TOS" "HIVE" "KAFKA" "KINESIS" "ALI_OSS" "MINIO" "CFS" "LASFS" "MYSQL" "BYTEHOUSE" Example: "TOS"
required	object

Responses

Request samples

Payload

Content type

application/json

{"name": "s3_sales_report",
"type": "TOS",
"data": {"accessKey": "AKIA1B2C3D4E5F6G7H8IJKLM",
"secretKey": "94eUOh9w3yEFqJyGW2XdU8NHJO/yTI9RHen4e0iU"
}
}

Response samples

201
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
},
"data": {"id": 1
}
}

List connections

Authorizations:

BearerAuth

query Parameters

cursor	string Example: cursor=eyJ2YWx1ZSI6bnVsbCwic29ydF92YWx1ZSI6bnVsbH0=
limit	integer Example: limit=100

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"meta": {"nextCursor": "nextCursor",
"prevCursor": "prevCursor",
"offset": 4,
"total": 5
},
"error": {"message": "null if no error, otherwise, it will be error message"
},
"data": [{"id": 12345,
"name": "s3_sales_report",
"type": "TOS",
"createdAt": "2022-05-10T12:43:56.722117+08:00"
}
]
}

Update a connection

Authorizations:

BearerAuth

path Parameters

id

required

integer

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

name required	string Example: "s3_connection_updated" Name of the connection
required	object

Responses

Request samples

Payload

Content type

application/json

{"name": "s3_connection_updated",
"data": {"accessKey": "AKIA1B2C3D4E5F6G7H8IJKLM",
"secretKey": "94eUOh9w3yEFqJyGW2XdU8NHJO/yTI9RHen4e0iU"
}
}

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
}
}

Delete a connection

Authorizations:

BearerAuth

path Parameters

id

required

integer

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
}
}

Get masked connection

Authorizations:

BearerAuth

path Parameters

id

required

integer

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
},
"data": {"id": 48613,
"name": "TOS china source",
"type": "TOS",
"data": {"accessKey": "**********",
"secretKey": "*************"
},
"accountID": 3093442639250928000,
"userID": 1360734397924064800,
"createdAt": "2022-04-27T04:36:11Z"
}
}

Create an import job

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

name required	string (ImportJobName) Example: "s3-cell-towers-csv" A descriptive name, 128 chars or less
description	string [Optional] To describe the job in more details
connectionID	integer ID of the connection which provides credentials to read data from source, for ByteHouse import job, connectionID should be 0
required	object (ImportJobConfiguration)
required	object (ImportJobSourceSchema) Provides schema of the source data, optional for batch data sources
schemaFile	string Base64 encoded string of protobuf schema file, required for KAFKA PROTOBUF
state required	string (ImportJobState) Enum: "PUBLISHED" "DRAFT" DRAFT means the job is partially created.

Responses

Request samples

Payload

Content type

application/json

{"name": "s3-cell-towers-csv",
"description": "string",
"connectionID": 0,
"configuration": {"source": {"type": "TOS",
"properties": {"bucket": "bytehouse-data-express-test",
"region": "cn-north-1",
"fileNames": "cell_towers.json",
"pathPrefix": "shared/clickhouse/cell_towers/"
},
"parser": {"type": "CSV",
"properties": {"fieldSeparator": ",",
"encoding": "UTF-8",
"header": true,
"quote": "\""
}
}
},
"sink": {"tableUUID": "ed4549e4-ce9a-41eb-a67d-2117cbb16716",
"properties": {"loadingMode": "FULL_REFRESH"
}
},
"schema": {"strategy": "NAME_CUSTOM_MAPPING",
"columns": [{"sourceColumnName": "unit price",
"sinkColumnName": "unit_price"
}
]
}
},
"sourceSchema": {"properties": [{"name": "radio",
"type": "String",
"example": "UMTS"
}
]
},
"schemaFile": "string",
"state": "PUBLISHED"
}

Response samples

201
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
},
"data": {"id": 0
}
}

List import jobs

Authorizations:

BearerAuth

query Parameters

cursor	string Example: cursor=eyJ2YWx1ZSI6bnVsbCwic29ydF92YWx1ZSI6bnVsbH0=
limit	integer Example: limit=100

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"meta": {"nextCursor": "nextCursor",
"prevCursor": "prevCursor",
"offset": 4,
"total": 5
},
"error": {"message": "null if no error, otherwise, it will be error message"
},
"data": [{"id": 398,
"name": "sample-s3-sales-70",
"accountID": 8635733085987518000,
"sourceType": "TOS",
"tableUUID": "feb4b7a6-fbc7-4164-abf5-a705499b02f9",
"databaseName": "brian",
"tableName": "sales",
"createdAt": "2022-05-10T13:21:21+08:00",
"createdBy": "8628611004645993074",
"ingestedRecords": 0,
"lastExecutionStatus": "RUNNING",
"state": "PUBLISHED"
}
]
}

Get an import job

Authorizations:

BearerAuth

path Parameters

id

required

integer

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
},
"data": {"name": "s3-cell-towers-csv",
"description": "string",
"connectionID": 0,
"configuration": {"source": {"type": "TOS",
"properties": {"bucket": "bytehouse-data-express-test",
"region": "cn-north-1",
"fileNames": "cell_towers.json",
"pathPrefix": "shared/clickhouse/cell_towers/"
},
"parser": {"type": "CSV",
"properties": {"fieldSeparator": ",",
"encoding": "UTF-8",
"header": true,
"quote": "\""
}
}
},
"sink": {"tableUUID": "ed4549e4-ce9a-41eb-a67d-2117cbb16716",
"properties": {"loadingMode": "FULL_REFRESH"
}
},
"schema": {"strategy": "NAME_CUSTOM_MAPPING",
"columns": [{"sourceColumnName": "unit price",
"sinkColumnName": "unit_price"
}
]
}
},
"sourceSchema": {"properties": [{"name": "radio",
"type": "String",
"example": "UMTS"
}
]
},
"schemaFile": "string",
"state": "PUBLISHED"
}
}

Update an import job

Authorizations:

BearerAuth

path Parameters

id

required

integer

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

name required	string (ImportJobName) Example: "s3-cell-towers-csv" A descriptive name, 128 chars or less
description	string [Optional] To describe the job in more details
connectionID	integer ID of the connection which provides credentials to read data from source, for ByteHouse import job, connectionID should be 0
required	object (ImportJobConfiguration)
required	object (ImportJobSourceSchema) Provides schema of the source data, optional for batch data sources
schemaFile	string Base64 encoded string of protobuf schema file, required for KAFKA PROTOBUF
state required	string (ImportJobState) Enum: "PUBLISHED" "DRAFT" DRAFT means the job is partially created.

Responses

Request samples

Payload

Content type

application/json

{"name": "s3-cell-towers-csv",
"description": "string",
"connectionID": 0,
"configuration": {"source": {"type": "TOS",
"properties": {"bucket": "bytehouse-data-express-test",
"region": "cn-north-1",
"fileNames": "cell_towers.json",
"pathPrefix": "shared/clickhouse/cell_towers/"
},
"parser": {"type": "CSV",
"properties": {"fieldSeparator": ",",
"encoding": "UTF-8",
"header": true,
"quote": "\""
}
}
},
"sink": {"tableUUID": "ed4549e4-ce9a-41eb-a67d-2117cbb16716",
"properties": {"loadingMode": "FULL_REFRESH"
}
},
"schema": {"strategy": "NAME_CUSTOM_MAPPING",
"columns": [{"sourceColumnName": "unit price",
"sinkColumnName": "unit_price"
}
]
}
},
"sourceSchema": {"properties": [{"name": "radio",
"type": "String",
"example": "UMTS"
}
]
},
"schemaFile": "string",
"state": "PUBLISHED"
}

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
}
}

Delete an import job

Authorizations:

BearerAuth

path Parameters

id

required

integer

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
}
}

Rename an import job

Authorizations:

BearerAuth

path Parameters

id

required

integer

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

name	string Example: "Job Updated Name" New name of import job

Responses

Request samples

Payload

Content type

application/json

{"name": "Job Updated Name"
}

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
}
}

Update an import job description

Authorizations:

BearerAuth

path Parameters

id

required

integer

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

description

string

Example: "Job Updated Description"

New description of import job

Responses

Request samples

Payload

Content type

application/json

{"description": "Job Updated Description"
}

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
}
}

Get the starting arguments for a specified import job

Authorizations:

BearerAuth

path Parameters

id

required

integer

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
},
"data": {"source.properties.fileStagingLocation": {"description": "Full path of uploaded file for the local ingestion job",
"type": "string",
"default": "employees.csv",
"required": true
}
}
}

Start a specified import job

Authorizations:

BearerAuth

path Parameters

id

required

integer

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

Starting Argument of the file

One of

source.properties.fileNames

string

Example: "Forestry_Planting_Spaces.csv"

Responses

Request samples

Payload

Content type

application/json

Example

StartImportJobS3Request

{"source.properties.fileNames": "Forestry_Planting_Spaces.csv"
}

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
},
"data": {"executionID": "fc276d11-381a-43ec-b7d9-cbb76a90d057"
}
}

Stop a specified import job

Authorizations:

BearerAuth

path Parameters

id

required

integer

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
}
}

List executions for a specified import job

Authorizations:

BearerAuth

path Parameters

id

required

integer

query Parameters

cursor	string Example: cursor=eyJ2YWx1ZSI6bnVsbCwic29ydF92YWx1ZSI6bnVsbH0=
limit	integer Example: limit=100

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"meta": {"nextCursor": "nextCursor",
"prevCursor": "prevCursor",
"offset": 4,
"total": 5
},
"error": {"message": "null if no error, otherwise, it will be error message"
},
"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"jobID": 28834,
"jobName": "s3-cell-towers-csv",
"sourceType": "TOS",
"startedAt": "2022-05-12T03:28:22Z",
"durationInMs": 10760,
"status": "RUNNING",
"diagnostics": "",
"startedBy": 1360734397924064800,
"numIngestedRecords": 0,
"tableUUID": "5f7ae696-651c-4252-b193-74a830c1f21a",
"percentageCompletion": 99.9,
"estimatedTimeLeftInMs": 0
}
]
}

List executions

Authorizations:

BearerAuth

query Parameters

cursor	string Example: cursor=eyJ2YWx1ZSI6bnVsbCwic29ydF92YWx1ZSI6bnVsbH0=
limit	integer Example: limit=100

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"meta": {"nextCursor": "nextCursor",
"prevCursor": "prevCursor",
"offset": 4,
"total": 5
},
"error": {"message": "null if no error, otherwise, it will be error message"
},
"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"jobID": 40449,
"jobName": "s3-cell-towers-csv",
"sourceType": "TOS",
"category": "BATCH",
"tableUUID": "feb4b7a6-fbc7-4164-abf5-a705499b02f9",
"databaseName": "brian",
"tableName": "sales",
"startedAt": "2022-05-10T13:21:21+08:00",
"startedBy": 8628611004645993000,
"durationInMs": 12420,
"status": "RUNNING",
"diagnostics": "string",
"numIngestedRecords": 0,
"numRejectedRecords": 0,
"percentageCompletion": 99.9,
"estimatedTimeLeftInMs": 0
}
]
}

Get execution details

Authorizations:

BearerAuth

path Parameters

id

required

string <uuid>

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
},
"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"jobID": 40395,
"connectionID": 48613,
"status": "RUNNING",
"statusChangedAt": "2022-05-04T07:12:31Z",
"accountID": 3093442639250928000,
"userID": 1360734397924064800,
"createdAt": "2022-04-27T04:36:11Z",
"startedAt": "2022-04-27T04:36:11Z",
"finishedAt": "0001-01-01T00:00:00Z",
"durationInMs": 614179673,
"sourceType": "TOS",
"configuration": {"source": {"type": "TOS",
"properties": {"bucket": "bytehouse-data-express-test",
"region": "cn-north-1",
"fileNames": "cell_towers.json",
"pathPrefix": "shared/clickhouse/cell_towers/"
},
"parser": {"type": "CSV",
"properties": {"fieldSeparator": ",",
"encoding": "UTF-8",
"header": true,
"quote": "\""
}
}
},
"sink": {"tableUUID": "ed4549e4-ce9a-41eb-a67d-2117cbb16716",
"properties": {"loadingMode": "FULL_REFRESH"
}
},
"schema": {"strategy": "NAME_CUSTOM_MAPPING",
"columns": [{"sourceColumnName": "unit price",
"sinkColumnName": "unit_price"
}
]
}
},
"sourceSchema": {"properties": [{"name": "radio",
"type": "String",
"example": "UMTS"
}
]
},
"schemaFile": "",
"diagnostics": "",
"numIngestedRecords": 0,
"numRejectedRecords": 0,
"percentageCompletion": 99.9,
"estimatedTimeLeftInMs": 0
}
}

Get Execution Logs, currently public api does not support logs from kafka

Authorizations:

BearerAuth

path Parameters

id

required

string <uuid>

query Parameters

limit

integer

Example: limit=100

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

500

Content type

application/json

{"error": {"message": "something went wrong, please refer to document or find help from tech support"
}
}

Get historical consuming status for a specified Kafka execution

Get historical consuming status of a Kafka execution including current offset, lag and consumption speed. The response will be an array of consuming status of time windows in the period from now back trace to now - 'period' (from query parameter). The time window length is specified by the 'granularity' query parameter.

Authorizations:

BearerAuth

path Parameters

id

required

string

Example: b36fa16e-a0ce-4274-a744-621357180928

query Parameters

partition required	integer Kafka topic partition used to query kafka consuming status.
period required	string Example: period=1h Time period to request for kafka historical consuming status and the value should be a valid duration string according to https://pkg.go.dev/time#ParseDuration.
granularity required	string Example: granularity=2m Time granularity to request for kafka historical consuming status and the value should be a valid duration string according to https://pkg.go.dev/time#ParseDuration.

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
},
"data": [{"currentOffset": 12345,
"lag": 2,
"consumptionSpeed": 3.2,
"time": "2022-05-12T11:15:00.000+08:00"
}
]
}

Virtual Warehouse

List virtual warehouses

Authorizations:

BearerAuth

query Parameters

limit	integer Example: limit=100 limitation of the response row count. limit value should >= 0; default value is 10, if no "limit" parameter passed, 10 will be set by default; max value is 100, if 120 passed, which exceed 100, will be corrected to 100.
offset	integer Example: offset=200 skip specified number of elements, offset shuold be >= 0

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"data": [{"id": "vw-123456789-vwname",
"name": "depart1_name2",
"description": "some description about this VW",
"configID": 123456,
"status": "up",
"autoSuspend": 5,
"autoResume": true,
"createdAt": "2020-11-23T09:23:55.840932013Z",
"lastModifiedAt": "2020-11-23T09:23:55.840932013Z"
}
],
"meta": {"offset": 4,
"total": 5
}
}

Create a virtual warehouse

Authorizations:

BearerAuth

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

name required	string (VWName) Example: "depart1_name2" vw name. string length should > 0 and < 32; may contain digital, lower case letter or '_'; should start with lower case letter; should end with digital or lower case letter.
status	string (VWStatusParam) Default: "up" Example: "up" indicate target status of the vw. "up"-run/resume; "down"-suspend.
autoSuspend	integer (VWAutoSuspend) Default: 0 Example: 5 VW will auto suspend after x minutes of idleness. If set to 0(default), VW will never auto suspend. The value should be >= 0;
autoResume	boolean (VWAutoResume) Default: false Example: true If set to true, the VW will try auto resume when query arrives.
configID required	integer (VWConfigID) Example: 123456 configID should > 0, you can get available resource settings by "list config" api.
description	string (VWDescription) Default: "" Example: "some description about this VW"

Responses

Request samples

Payload

Content type

application/json

{"name": "depart1_name2",
"status": "up",
"autoSuspend": 5,
"autoResume": true,
"configID": 123456,
"description": "some description about this VW"
}

Response samples

200
500

Content type

application/json

{"name": "string",
"vwID": "vw-123456789-vwname",
"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
}
}

Get a virtual warehouse

Getting the virtual warehouse details by name

Authorizations:

BearerAuth

path Parameters

name

required

string

Example: seg1_vw2

vw name

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"id": "vw-123456789-vwname",
"name": "depart1_name2",
"description": "some description about this VW",
"configID": 123456,
"status": "up",
"autoSuspend": 5,
"autoResume": true,
"createdAt": "2020-11-23T09:23:55.840932013Z",
"lastModifiedAt": "2020-11-23T09:23:55.840932013Z",
"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
}
}

Update a virtual warehouse

Authorizations:

BearerAuth

path Parameters

name

required

string

Example: seg1_vw2

vw name

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Request Body schema: application/json

description	string or null (VWDescriptionNullable) Example: "some description about this VW"
configID	integer or null (VWConfigIDNullable) Example: 123456 configID should > 0, you can get available resource settings by "list config" api.
status	string or null (VWStatusParamNullable) Example: "up" indicate target status of the vw. "up"-run/resume; "down"-suspend.
autoSuspend	integer or null (VWAutoSuspendNullable) Example: 5 VW will auto suspend after x minutes of idleness. If set to 0(default), VW will never auto suspend. The value should be >= 0;
autoResume	boolean or null (VWAutoResumeNullable) Example: true If set to true, the VW will try auto resume when query arrives.

Responses

Request samples

Payload

Content type

application/json

{"description": "some description about this VW",
"configID": 123456,
"status": "up",
"autoSuspend": 5,
"autoResume": true
}

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
}
}

Delete a virtual warehouse

Authorizations:

BearerAuth

path Parameters

name

required

string

Example: seg1_vw2

vw name

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"message": "Success",
"error": {"message": "omitempty if no error, otherwise, it will be error message"
}
}

List virtual warehouse configurations

Authorizations:

BearerAuth

query Parameters

limit	integer Example: limit=100 limitation of the response row count. limit value should >= 0; default value is 10, if no "limit" parameter passed, 10 will be set by default; max value is 100, if 120 passed, which exceed 100, will be corrected to 100.
offset	integer Example: offset=200 skip specified number of elements, offset shuold be >= 0

header Parameters

X-User-ActiveRole

string

Example: AccountAdmin

User Active Role

Responses

Response samples

200
500

Content type

application/json

{"data": [{"id": 10,
"name": "XS",
"cpu": "0.6",
"memory": "2Gi",
"replica": 2,
"isDefault": true,
"createdAt": "2020-11-23T09:23:55.840932013Z"
}
],
"meta": {"offset": 4,
"total": 5
}
}