Bytehouse
API docs by Redocly

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

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

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

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

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

Content type
application/json
{
  • "name": "db_name",
  • "description": "testing database, please don't delete"
}

Response samples

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

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

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

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

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

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

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

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.

Responses

Request samples

Content type
application/json
{
  • "name": "table_name",
  • "description": "Hello Table",
  • "columns": [
    ],
  • "orderByKeys": [
    ],
  • "samplingKey": "ColumnID",
  • "partitionKeys": [
    ],
  • "primaryKeys": [
    ],
  • "ttl": {
    },
  • "uniqueKey": {
    },
  • "clusterKey": {
    }
}

Response samples

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

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

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

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

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

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

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

Content type
application/json
{
  • "addColumns": [
    ],
  • "dropColumns": [
    ],
  • "modifyColumns": [
    ],
  • "renameColumns": [
    ],
  • "ttl": {
    },
  • "isRemoveTTL": false
}

Response samples

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

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

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

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

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

Content type
application/json
{
  • "partitionNames": [
    ]
}

Response samples

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

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

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

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

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

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

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

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

Content type
application/json
{
  • "data": {
    },
  • "message": "Success",
  • "error": {
    }
}

Queries

Submit a synchronous query

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)

Responses

Request samples

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
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Abort a synchronous query

Authorizations:
BearerAuth
header Parameters
X-QuerySession-ID
string

Query/Worksheet session ID

X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

Responses

Response samples

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

Kill a sync 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

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

Submit an asynchronous query

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

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

Content type
application/json
{
  • "data": [
    ]
}

Kill a 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

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

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

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

Retrieve the results for a specified asynchronous query

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

Content type
application/json
{
  • "data": [
    ]
}

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

Content type
application/json
{
  • "query": "USE TUTORIAL_DB; SELECT * FROM TUTORIAL_DB.Customer;",
  • "userInfo": {
    }
}

Response samples

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

Retrieve dialects available for a user

Authorizations:
BearerAuth
header Parameters
X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

IAM

Create an API key

Create a new API key for current user. The number of API key is limited to 2 per user.

Authorizations:
BearerAuth
header Parameters
X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

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

Content type
application/json
{
  • "noExpiry": false,
  • "expiryInDays": 90,
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

List user API keys

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

Authorizations:
BearerAuth
header Parameters
X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

Responses

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": [
    ]
}

Delete an API key

Authorizations:
BearerAuth
path Parameters
api_key_id
required
string
Example: qUNomoCoqSokljuoRs5z

ID of User's API Key

header Parameters
X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

Responses

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    }
}

Enables or disables an API key

Authorizations:
BearerAuth
path Parameters
api_key_id
required
string
Example: qUNomoCoqSokljuoRs5z

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"

Responses

Request samples

Content type
application/json
{
  • "status": "ENABLED"
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    }
}

Update the expiry for a specified API key

Authorizations:
BearerAuth
path Parameters
api_key_id
required
string
Example: qUNomoCoqSokljuoRs5z

ID of User's API Key

header Parameters
X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

Request Body schema: application/json
addExpiryInDays
integer
Example: 90

Responses

Request samples

Content type
application/json
{
  • "addExpiryInDays": 90
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    }
}

List roles

Authorizations:
BearerAuth
header Parameters
X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

Responses

Response samples

Content type
application/json
{
  • "message": "Success",
  • "meta": {
    },
  • "error": {
    },
  • "data": {
    }
}

List assignments

Authorizations:
BearerAuth
query Parameters
UserID
integer
header Parameters
X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

Responses

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

Assign a role to a specified user

Assigning a role to a user enables the target user to assume the role and gain access to all the resources accessible by the role. To use this, the assigning role has to have the permission to assign role(s), e.g. SystemAdmin.

Authorizations:
BearerAuth
header Parameters
X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

Request Body schema: application/json
UserID
integer
Example: 1336688750

Target user ID.

RoleName
string
Example: "SystemAdmin"

Name of the role to assign. Role must exist under the account.

Responses

Request samples

Content type
application/json
{
  • "UserID": 1336688750,
  • "RoleName": "SystemAdmin"
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

Un-assign a role from a specified user

Authorizations:
BearerAuth
header Parameters
X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

Request Body schema: application/json
UserID
integer
Example: 1336688750

Target user ID.

RoleName
string
Example: "SystemAdmin"

Name of the role to assign. Role must exist under the account.

Responses

Request samples

Content type
application/json
{
  • "UserID": 1336688750,
  • "RoleName": "SystemAdmin"
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

Grant permissions to a specified role

Authorizations:
BearerAuth
header Parameters
X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

Request Body schema: application/json
RoleName
string
ByteHouseResourceID
string
SecureObjectTypeName
string
ActionName
string
GrantOption
boolean

Responses

Request samples

Content type
application/json
{
  • "RoleName": "string",
  • "ByteHouseResourceID": "string",
  • "SecureObjectTypeName": "string",
  • "ActionName": "string",
  • "GrantOption": true
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

Revoke permissions from a specified role

Authorizations:
BearerAuth
header Parameters
X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

Request Body schema: application/json
RoleName
string
ByteHouseResourceID
string
SecureObjectTypeName
string
ActionName
string

Responses

Request samples

Content type
application/json
{
  • "RoleName": "string",
  • "ByteHouseResourceID": "string",
  • "SecureObjectTypeName": "string",
  • "ActionName": "string"
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    }
}

List permissions of a specified role

Authorizations:
BearerAuth
query Parameters
RoleName
required
string
ByteHouseResourceID
required
string
SecureObjectTypeName
required
string
header Parameters
X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

Responses

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

Retrieve the account status

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

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

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

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

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

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

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

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

Content type
application/json
{
  • "name": "s3_sales_report",
  • "type": "TOS",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

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

Content type
application/json
{
  • "message": "Success",
  • "meta": {
    },
  • "error": {
    },
  • "data": [
    ]
}

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

Content type
application/json
{
  • "name": "s3_connection_updated",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    }
}

Delete a connection

Authorizations:
BearerAuth
path Parameters
id
required
integer
header Parameters
X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

Responses

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    }
}

Get masked connection

Authorizations:
BearerAuth
path Parameters
id
required
integer
header Parameters
X-User-ActiveRole
string
Example: AccountAdmin

User Active Role

Responses

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

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

Content type
application/json
{
  • "name": "s3-cell-towers-csv",
  • "description": "string",
  • "connectionID": 0,
  • "configuration": {
    },
  • "sourceSchema": {
    },
  • "schemaFile": "string",
  • "state": "PUBLISHED"
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

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

Content type
application/json
{
  • "message": "Success",
  • "meta": {
    },
  • "error": {
    },
  • "data": [
    ]
}

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

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

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

Content type
application/json
{
  • "name": "s3-cell-towers-csv",
  • "description": "string",
  • "connectionID": 0,
  • "configuration": {
    },
  • "sourceSchema": {
    },
  • "schemaFile": "string",
  • "state": "PUBLISHED"
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    }
}

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

Content type
application/json
{
  • "message": "Success",
  • "error": {
    }
}

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

Content type
application/json
{
  • "name": "Job Updated Name"
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    }
}

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

Content type
application/json
{
  • "description": "Job Updated Description"
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    }
}

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

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

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

Content type
application/json
Example
{
  • "source.properties.fileNames": "Forestry_Planting_Spaces.csv"
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

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

Content type
application/json
{
  • "message": "Success",
  • "error": {
    }
}

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

Content type
application/json
{
  • "message": "Success",
  • "meta": {
    },
  • "error": {
    },
  • "data": [
    ]
}

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

Content type
application/json
{
  • "message": "Success",
  • "meta": {
    },
  • "error": {
    },
  • "data": [
    ]
}

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

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": {
    }
}

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

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

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

Content type
application/json
{
  • "message": "Success",
  • "error": {
    },
  • "data": [
    ]
}

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

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

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

Content type
application/json
{
  • "name": "depart1_name2",
  • "status": "up",
  • "autoSuspend": 5,
  • "autoResume": true,
  • "configID": 123456,
  • "description": "some description about this VW"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "vwID": "vw-123456789-vwname",
  • "message": "Success",
  • "error": {
    }
}

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

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

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

Content type
application/json
{
  • "description": "some description about this VW",
  • "configID": 123456,
  • "status": "up",
  • "autoSuspend": 5,
  • "autoResume": true
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "error": {
    }
}

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

Content type
application/json
{
  • "message": "Success",
  • "error": {
    }
}

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

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}