Skip to content
TD API/
/Tables

Treasure Data API (3)

Download OpenAPI description
td_api_v3-public.json
td_api_v3-public.yaml
Languages
Servers

https://api.treasuredata.com/v3/

https://api.treasuredata.co.jp/v3/

https://api.ap02.treasuredata.com/v3/

https://api.eu01.treasuredata.com/v3/

Access Control - Policies

Operations

Access Control - Permissions

Operations

Access Control - Users

Operations

Access Control - Policy Groups

Operations

Connections

Operations

Databases

Operations

Jobs

Operations

Policy Group Tags

Operations

Schedules

Operations

Tables

Operations

Get tables

Request

Retrieves a list of tables according to database specified.

Security
ApiKeyAuth
Path
database_namestringrequired

database name

Example: Alpha
Query
include_descriptionsboolean

When true, includes table descriptions and column descriptions in the schema field

Default false
curl -i -X GET \
  'https://api.treasuredata.com/v3/table/list/Alpha?include_descriptions=false' \
  -H 'Authorization: TD1 <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
databasestringrequired

database name

Example: "Alpha"
tablesArray of objects(Table)required
tables[].​idinteger(TableId)required
Example: 11
tables[].​countintegerrequired
Example: 1000
tables[].​counter_updated_at(string or null) or DateTimeISO8601 (string)required
Any of:
string or null
tables[].​created_atstring(DateTimeAsString)\d{4}-\d{2}-\d{2}\s\d{2}:\d{2}:\d{2}\s(([+-]\...required

Datetime in custom format (2020-12-31 11:22:33 -0500 or 2020-12-31 11:22:33 UTC for UTC)

Example: "2020-12-31 11:22:33 UTC"
tables[].​delete_protectedbooleanrequired
Example: true
tables[].​estimated_storage_sizeintegerrequired
Example: 1073741824
tables[].​expire_daysinteger or nullrequired
Example: 30
tables[].​last_log_timestampinteger or nullrequired
Example: 1356998400
tables[].​namestringrequired
Example: "Bravo"
tables[].​descriptionstring or null

user-provided description of the table

Example: "Click events."
tables[].​schemastringrequired

JSON-encoded table schema. When include_descriptions=true, contains column descriptions in format [[name, type, alias, description], ...]

tables[].​typestringrequired
Value"log"
Example: "log"
tables[].​updated_atstring(DateTimeAsString)\d{4}-\d{2}-\d{2}\s\d{2}:\d{2}:\d{2}\s(([+-]\...required

Datetime in custom format (2020-12-31 11:22:33 -0500 or 2020-12-31 11:22:33 UTC for UTC)

Example: "2020-12-31 11:22:33 UTC"
tables[].​include_vbooleanDeprecatedrequired

when true, Hive queries can access a virtual column "v" which contains a map of every data column's name to its value (represented as a string). Prefer to set a schema on the table instead of using "v".

Example: false
Response
application/json
{
  "database": "Alpha",
  "tables": [
    { … }
  ]
}

Get table

Request

Shows a table according to specified database and table.

Security
ApiKeyAuth
Path
database_namestringrequired

database name

Example: Alpha
table_namestringrequired
Example: Bravo
Query
include_descriptionsboolean

When true, includes table descriptions and column descriptions in the schema field

Default false
curl -i -X GET \
  'https://api.treasuredata.com/v3/table/show/Alpha/Bravo?include_descriptions=false' \
  -H 'Authorization: TD1 <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
idinteger(TableId)required
Example: 11
countintegerrequired
Example: 1000
counter_updated_at(string or null) or DateTimeISO8601 (string)required
Any of:
string or null
created_atstring(DateTimeAsString)\d{4}-\d{2}-\d{2}\s\d{2}:\d{2}:\d{2}\s(([+-]\...required

Datetime in custom format (2020-12-31 11:22:33 -0500 or 2020-12-31 11:22:33 UTC for UTC)

Example: "2020-12-31 11:22:33 UTC"
delete_protectedbooleanrequired
Example: true
estimated_storage_sizeintegerrequired
Example: 1073741824
expire_daysinteger or nullrequired
Example: 30
last_log_timestampinteger or nullrequired
Example: 1356998400
namestringrequired
Example: "Bravo"
descriptionstring or null

user-provided description of the table

Example: "Click events."
schemastringrequired

JSON-encoded table schema. When include_descriptions=true, contains column descriptions in format [[name, type, alias, description], ...]

typestringrequired
Value"log"
Example: "log"
updated_atstring(DateTimeAsString)\d{4}-\d{2}-\d{2}\s\d{2}:\d{2}:\d{2}\s(([+-]\...required

Datetime in custom format (2020-12-31 11:22:33 -0500 or 2020-12-31 11:22:33 UTC for UTC)

Example: "2020-12-31 11:22:33 UTC"
include_vbooleanDeprecatedrequired

when true, Hive queries can access a virtual column "v" which contains a map of every data column's name to its value (represented as a string). Prefer to set a schema on the table instead of using "v".

Example: false
Response
application/json
{
  "id": 11,
  "count": 1000,
  "counter_updated_at": "string",
  "created_at": "2020-12-31 11:22:33 UTC",
  "delete_protected": true,
  "estimated_storage_size": 1073741824,
  "expire_days": 30,
  "include_v": false,
  "last_log_timestamp": 1356998400,
  "name": "Bravo",
  "description": "Click events.",
  "schema": "string",
  "type": "log",
  "updated_at": "2020-12-31 11:22:33 UTC"
}

Delete table

Request

Deletes specified table.

Security
ApiKeyAuth
Path
database_namestringrequired

database name

Example: Alpha
table_namestringrequired
Example: Bravo
curl -i -X POST \
  https://api.treasuredata.com/v3/table/delete/Alpha/Bravo \
  -H 'Authorization: TD1 <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
databasestringrequired

database name

Example: "Alpha"
tablestringrequired
Example: "Bravo"
typestringrequired
Value"log"
Example: "log"
Response
application/json
{
  "database": "Alpha",
  "table": "Bravo",
  "type": "log"
}

Create table with specified type

Request

Creates a table of a specified type. Currently only 'log' is supported as table_type. This endpoint supports creating tables with schema, options, and can copy properties from existing tables. Schema can include column descriptions in the format [name, type, alias, description].

Security
ApiKeyAuth
Path
database_namestringrequired

database name

Example: Alpha
table_namestringrequired
Example: Bravo
table_typestringrequired
Value"log"
Example: log
Query
idempotent_keystring(IdempotentKey)

A unique key to ensure idempotency of requests

source_tablestring

Name of an existing table to copy metadata from

including_propertiesboolean

When true, distribution and other properties will be copied from source_table

Bodyapplication/x-www-form-urlencoded
descriptionstring or null

user-provided description of the table

Example: "Click events."
schemaArray of TableSchemaAsArray (strings) or TableSchemaAsString (string)
One of:
include_vbooleanDeprecated

when true, Hive queries can access a virtual column "v" which contains a map of every data column's name to its value (represented as a string). Prefer to set a schema on the table instead of using "v".

Example: false
curl -i -X POST \
  'https://api.treasuredata.com/v3/table/create/Alpha/Bravo/log?idempotent_key=string&source_table=string&including_properties=true' \
  -H 'Authorization: TD1 <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d include_v=false \
  -d 'description=Click events.' \
  -d 'schema[0]=name' \
  -d 'schema[0]=string' \
  -d 'schema[0]=first_name' \
  -d 'schema[1]=creation_date' \
  -d 'schema[1]=long'

Responses

OK

Bodyapplication/json
databasestringrequired

database name

Example: "Alpha"
tablestringrequired
Example: "Bravo"
typestringrequired
Value"log"
Example: "log"
Response
application/json
{
  "database": "Alpha",
  "table": "Bravo",
  "type": "log"
}

Create table

Request

Creates a table with default type 'log'. This endpoint offers the same functionality as the typed endpoint but without explicitly specifying the table type. Schema can include column descriptions in the format [name, type, alias, description].

Security
ApiKeyAuth
Path
database_namestringrequired

database name

Example: Alpha
table_namestringrequired
Example: Bravo
Query
idempotent_keystring(IdempotentKey)

A unique key to ensure idempotency of requests

source_tablestring

Name of an existing table to copy metadata from

including_propertiesboolean

When true, distribution and other properties will be copied from source_table

Bodyapplication/x-www-form-urlencoded
descriptionstring or null

user-provided description of the table

Example: "Click events."
schemaArray of TableSchemaAsArray (strings) or TableSchemaAsString (string)
One of:
include_vbooleanDeprecated

when true, Hive queries can access a virtual column "v" which contains a map of every data column's name to its value (represented as a string). Prefer to set a schema on the table instead of using "v".

Example: false
curl -i -X POST \
  'https://api.treasuredata.com/v3/table/create/Alpha/Bravo?idempotent_key=string&source_table=string&including_properties=true' \
  -H 'Authorization: TD1 <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d include_v=false \
  -d 'description=Click events.' \
  -d 'schema[0]=name' \
  -d 'schema[0]=string' \
  -d 'schema[0]=first_name' \
  -d 'schema[1]=creation_date' \
  -d 'schema[1]=long'

Responses

OK

Bodyapplication/json
databasestringrequired

database name

Example: "Alpha"
tablestringrequired
Example: "Bravo"
typestringrequired
Value"log"
Example: "log"
Response
application/json
{
  "database": "Alpha",
  "table": "Bravo",
  "type": "log"
}

Update table

Request

Updates a table.

Security
ApiKeyAuth
Path
database_namestringrequired

database name

Example: Alpha
table_namestringrequired
Example: Bravo
Bodyapplication/x-www-form-urlencoded
detect_schemaboolean
Example: true
expire_daysinteger or null
Example: 30
namestring
Example: "Bravo"
descriptionstring or null

user-provided description of the table

Example: "Click events."
schemaArray of TableSchemaAsArray (strings) or TableSchemaAsString (string)
One of:
ignore_duplicate_schemaboolean
Example: true
overwriteboolean

whether to override a possible existing table in case of updating the name

Example: false
include_vbooleanDeprecated

when true, Hive queries can access a virtual column "v" which contains a map of every data column's name to its value (represented as a string). Prefer to set a schema on the table instead of using "v".

Example: false
curl -i -X POST \
  https://api.treasuredata.com/v3/table/update/Alpha/Bravo \
  -H 'Authorization: TD1 <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d detect_schema=true \
  -d expire_days=30 \
  -d include_v=false \
  -d name=Bravo \
  -d 'description=Click events.' \
  -d 'schema[0]=name' \
  -d 'schema[0]=string' \
  -d 'schema[0]=first_name' \
  -d 'schema[1]=creation_date' \
  -d 'schema[1]=long' \
  -d ignore_duplicate_schema=true \
  -d overwrite=false

Responses

OK

Bodyapplication/json
databasestringrequired

database name

Example: "Alpha"
tablestringrequired
Example: "Bravo"
typestringrequired
Value"log"
Example: "log"
Response
application/json
{
  "database": "Alpha",
  "table": "Bravo",
  "type": "log"
}

Rename table

Request

Renames a specified table.

Security
ApiKeyAuth
Path
database_namestringrequired

database name

Example: Alpha
current_table_namestringrequired
Example: Bravo
new_table_namestringrequired
Example: Bravo
curl -i -X POST \
  https://api.treasuredata.com/v3/table/rename/Alpha/Bravo/Bravo \
  -H 'Authorization: TD1 <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
databasestringrequired

database name

Example: "Alpha"
tablestringrequired
Example: "Bravo"
typestringrequired
Value"log"
Example: "log"
Response
application/json
{
  "database": "Alpha",
  "table": "Bravo",
  "type": "log"
}

Swap tables

Request

Swaps specified tables.

Security
ApiKeyAuth
Path
database_namestringrequired

database name

Example: Alpha
table_name_1stringrequired
Example: Bravo
table_name_2stringrequired
Example: Bravo
curl -i -X POST \
  https://api.treasuredata.com/v3/table/swap/Alpha/Bravo/Bravo \
  -H 'Authorization: TD1 <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
databasestringrequired

database name

Example: "Alpha"
table1stringrequired
Example: "Bravo"
table2stringrequired
Example: "Bravo"
Response
application/json
{
  "database": "Alpha",
  "table1": "Bravo",
  "table2": "Bravo"
}

Tail table

Request

Shows the last record in a table.

Security
ApiKeyAuth
Path
database_namestringrequired

database name

Example: Alpha
table_namestringrequired
Example: Bravo
path_formatstringrequired
Enum"json""msgpack"
Query
formatstring
Enum"json""msgpack"
curl -i -X GET \
  'https://api.treasuredata.com/v3/table/tail/Alpha/Bravo{path_format}?format=json' \
  -H 'Authorization: TD1 <YOUR_TOKEN_HERE>'

Responses

OK

Body
Array [
Any of:

Can be any value, including null.

string or null

Can be any value, including null.

]
Response
[
  "string"
]

Get table distribution

Request

Retrieve a table distribution.

Security
ApiKeyAuth
Path
database_namestringrequired

database name

Example: Alpha
table_namestringrequired
Example: Bravo
curl -i -X GET \
  https://api.treasuredata.com/v3/table/distribution/Alpha/Bravo \
  -H 'Authorization: TD1 <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
bucket_countintegerrequired
Example: 50
partition_functionstringrequired
Example: "hash"
columnsArray of objects(ColumnSchema)required
columns[].​keystringrequired
Example: "age"
columns[].​typestringrequired
Example: "integer"
columns[].​namestringrequired
Example: "age"
Response
application/json
{
  "bucket_count": 50,
  "partition_function": "hash",
  "columns": [
    { … }
  ]
}

Change database

Request

Changes to the specified table database.

Security
ApiKeyAuth
Path
database_namestringrequired

database name

Example: Alpha
table_namestringrequired
Example: Bravo
Bodyapplication/x-www-form-urlencoded
dest_database_namestringrequired

database name

Example: "Alpha"
curl -i -X POST \
  https://api.treasuredata.com/v3/table/change_database/Alpha/Bravo \
  -H 'Authorization: TD1 <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d dest_database_name=Alpha

Responses

OK

Bodyapplication/json
databasestringrequired

database name

Example: "Alpha"
tablestringrequired
Example: "Bravo"
typestringrequired
Value"log"
Example: "log"
Response
application/json
{
  "database": "Alpha",
  "table": "Bravo",
  "type": "log"
}

Transfer table to a different account

Request

Transfer the specified table to a different account. (Limited Access)

Security
ApiKeyAuth
Path
database_namestringrequired

database name

Example: Alpha
table_namestringrequired
Example: Bravo
Headers
Secondary-Authorizationstring^TD1 [0-9a-f/]+$

TD1 Authorization Header

Example: TD1 123/456789xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Bodyapplication/x-www-form-urlencoded
dest_database_namestringrequired

database name

Example: "Alpha"
dest_table_namestringrequired
Example: "Bravo"
idempotent_keystring(IdempotentKey)
curl -i -X POST \
  https://api.treasuredata.com/v3/table/transfer/Alpha/Bravo \
  -H 'Authorization: TD1 <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Secondary-Authorization: TD1 123/456789xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -d dest_database_name=Alpha \
  -d dest_table_name=Bravo \
  -d idempotent_key=string

Responses

OK

Bodyapplication/json
database_namestring
table_namestring
Response
application/json
{
  "database_name": "string",
  "table_name": "string"
}

Append table schema

Request

Appends the specified table schema.

Security
ApiKeyAuth
Path
database_namestringrequired

database name

Example: Alpha
table_namestringrequired
Example: Bravo
Bodyapplication/x-www-form-urlencoded
schemaArray of TableSchemaAsArray (strings) or TableSchemaAsString (string)required
One of:
Array [
string
curl -i -X POST \
  https://api.treasuredata.com/v3/table/append-schema/Alpha/Bravo \
  -H 'Authorization: TD1 <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'schema[0]=name' \
  -d 'schema[0]=string' \
  -d 'schema[0]=first_name' \
  -d 'schema[1]=creation_date' \
  -d 'schema[1]=long'

Responses

OK

Bodyapplication/json
databasestringrequired

database name

Example: "Alpha"
tablestringrequired
Example: "Bravo"
typestringrequired
Value"log"
Example: "log"
Response
application/json
{
  "database": "Alpha",
  "table": "Bravo",
  "type": "log"
}

Update table schema

Request

Updates the specified table schema. Schema can include column descriptions in the format [name, type, alias, description].

Security
ApiKeyAuth
Path
database_namestringrequired

database name

Example: Alpha
table_namestringrequired
Example: Bravo
Bodyapplication/x-www-form-urlencoded
namestring
Example: "table1_new_name"
schemaArray of TableSchemaAsArray (strings) or TableSchemaAsString (string)required
One of:
Array [
string
ignore_duplicate_schemaboolean
Example: true
detect_schemaboolean
Example: true
include_vboolean
Example: true
expire_daysinteger
Example: 1
overwriteboolean
Example: true
curl -i -X POST \
  https://api.treasuredata.com/v3/table/update-schema/Alpha/Bravo \
  -H 'Authorization: TD1 <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d name=table1_new_name \
  -d 'schema[0]=name' \
  -d 'schema[0]=string' \
  -d 'schema[0]=first_name' \
  -d 'schema[1]=creation_date' \
  -d 'schema[1]=long' \
  -d ignore_duplicate_schema=true \
  -d detect_schema=true \
  -d include_v=true \
  -d expire_days=1 \
  -d overwrite=true

Responses

OK

Bodyapplication/json
databasestringrequired

database name

Example: "Alpha"
tablestringrequired
Example: "Bravo"
typestringrequired
Value"log"
Example: "log"
Response
application/json
{
  "database": "Alpha",
  "table": "Bravo",
  "type": "log"
}

Users

Operations

Data Connector Restrictions

Operations