1. Overview #

The Apache® Gravitino Lance REST Catalog (hereinafter referred to as "Lance REST service") provides a set of HTTP APIs compatible with the Lance Namespace REST specification for managing the metadata of namespaces and tables.

Apache Gravitino, the names of other Apache projects, and the ASF logo are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries.

Typical scenarios include:

• Managing Lance table metadata through a unified REST entry point in multi-engine or multi-task systems
• When a data directory already exists in object storage (such as TOS), bringing it under management by registering it as a catalog
• In automated integration processes, performing idempotent creation, existence checks, metadata queries, and decommissioning cleanup

2. Path and identifier conventions #

2.1 Base URL #

The REST root path of the service always includes /lance, and the API path starts with /lance/v1:

• Base URL：https://{endpoint}/lance
• API prefix: /lance/v1/...

2.2 NamespaceId and TableId #

Lance REST uses the string id in the path to represent a namespace or table, with the default delimiter $:

• namespaceId：
  • Level 1: {catalog}
  • Level 2: {catalog}${schema}
• tableId：{catalog}${schema}${table}

The delimiter can be passed in via the query parameter delimiter (default is $).

2.3 URL encoding #

Characters such as $, @, and # in the URL path must be percent-encoded:

• $ → %24
• @ → %40
• # → %23

For example: demo_catalog$demo_schema should be processed as: demo_catalog%24demo_schema

3. Preparation before use #

3.1 Obtain the service endpoint and region #

You need to obtain:

• Service access endpoint (Endpoint)
• Region (such as cn-beijing, cn-shanghai)

3.2 Authentication and signature (AK/SK) #

In the Volcano Engine managed environment, the Lance REST service uses the Volcano Engine standard AK/SK signature authentication mechanism. Requests typically need to include:

• Authorization: HMAC-SHA256 ...
• X-Date: YYYYMMDD'T'HHMMSS'Z'
• (Optional) X-Expire: -1 | 0 | N (controls signature validity period)
• Region: {region}

For details on the signature algorithm and implementation, please refer to the official documentation: https://www.volcengine.com/docs/6369/67269

4. API reference #

4.1 General information #

Environment variables (example)

export LANCE_HOST='https://{endpoint}'
export LANCE_BASE="${LANCE_HOST}/lance"
export REGION='cn-beijing'

Common headers (recommended for production)

Common query parameters

Error response (example)
On failure, an error structure in application/json format is usually returned (field names are subject to actual response):

{
  "code": 404,
  "error": "Table not found",
  "type": "NoSuchTableException",
  "instance": "demo_catalog$demo_schema$demo_table",
  "detail": "..."
}

4.2 Namespace API #

4.2.1 List child namespaces (catalog list)

• Method: GET
• Path: /lance/v1/namespace/{id}/list

Input parameters

Request example

curl --location "${LANCE_BASE}/v1/namespace/root/list" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}"

Response example (200)

{
  "namespaces": ["demo_catalog", "demo_catalog2"],
  "page_token": null
}

4.2.2 Create a namespace

• Method: POST
• Path: /lance/v1/namespace/{id}/create

Input parameters

Request example: Create a level 1 namespace (catalog)

curl --location --request POST "${LANCE_BASE}/v1/namespace/demo_catalog/create" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{
    "mode": "create",
    "properties": {
      "comment": "created-by-demo"
    }
  }'

Request example: Create a level 2 namespace (schema)

curl --location --request POST "${LANCE_BASE}/v1/namespace/demo_catalog%24demo_schema/create" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{
    "mode": "create",
    "properties": {
      "location": "tos://{bucket}/{prefix}/"
    }
  }'

Response example (200)

{
  "properties": {
    "key": "value"
  }
}

4.2.3 Describe a namespace

• Method: POST
• Path: /lance/v1/namespace/{id}/describe

Input parameters

Request example

curl --location --request POST "${LANCE_BASE}/v1/namespace/demo_catalog%24demo_schema/describe" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{}'

Response example (200)

{
  "properties": {
    "location": "tos://{bucket}/{prefix}/"
  }
}

4.2.4 Check if a namespace exists

• Method: POST
• Path: /lance/v1/namespace/{id}/exists

Input parameters

Response

• Exists: 200 OK (usually no response body)
• Does not exist: 404 Not Found (returns error structure)

4.2.5 Delete a namespace

• Method: POST
• Path: /lance/v1/namespace/{id}/drop

Caution: Deleting a namespace is typically recursive and irreversible. It is recommended to verify in a test environment first.

Input parameters

Request example

curl --location --request POST "${LANCE_BASE}/v1/namespace/demo_catalog%24demo_schema/drop" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{"mode":"FAIL","behavior":"RESTRICT"}'

Response example (200)

{}

4.2.6 List tables under a namespace

• Method: GET
• Path: /lance/v1/namespace/{id}/table/list

Input parameters

Request example

curl --location "${LANCE_BASE}/v1/namespace/demo_catalog%24demo_schema/table/list" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}"

Response example (200)

{
  "tables": ["demo_catalog$demo_schema$demo_table"],
  "page_token": null
}

4.3 Table interface #

4.3.1 Create an empty table (store only metadata)

• Method: POST
• Path: /lance/v1/table/{id}/create-empty

Input parameters

Request example

curl --location --request POST "${LANCE_BASE}/v1/table/demo_catalog%24demo_schema%24demo_table0/create-empty" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{
    "location": "tos://{bucket}/{prefix}/demo_table0.lance",
    "properties": {"k": "v"}
  }'

Response example (200)

{
  "location": "tos://{bucket}/{prefix}/demo_table0.lance",
  "properties": {"key": "value"}
}

4.3.2 Register a table (recommended: manage an existing data directory)

• Method: POST
• Path: /lance/v1/table/{id}/register

Input parameters

Request example

curl --location --request POST "${LANCE_BASE}/v1/table/demo_catalog%24demo_schema%24demo_table/register" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{
    "location": "tos://{bucket}/{prefix}/demo_table.lance",
    "mode": "CREATE",
    "properties": {
      "desc": "demo",
      "lance.hms.write-schema": true
    }
  }'

Response example (200)

{
  "location": "tos://{bucket}/{prefix}/demo_table.lance",
  "properties": {
    "location": "tos://{bucket}/{prefix}/demo_table.lance",
    "lance.register": "true",
    "desc": "demo"
  }
}

4.3.3 Deregister a table (only deletes metadata, does not delete underlying data)

• Method: POST
• Path: /lance/v1/table/{id}/deregister

Input parameters

Request example

curl --location --request POST "${LANCE_BASE}/v1/table/demo_catalog%24demo_schema%24demo_table/deregister" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{}'

Response example (200)

{
  "location": "tos://{bucket}/{prefix}/demo_table.lance",
  "properties": {"key": "value"}
}

4.3.4 Check if a table exists

• Method: POST
• Path: /lance/v1/table/{id}/exists

Input parameters

Response

• Exists: 200 OK (usually no response body)
• Does not exist: 404 Not Found (returns error structure)

4.3.5 Describe a table

• Method: POST
• Path: /lance/v1/table/{id}/describe

Input parameters

Request example

curl --location --request POST "${LANCE_BASE}/v1/table/demo_catalog%24demo_schema%24demo_table/describe" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{}'

Response example (200)

{
  "location": "tos://{bucket}/{prefix}/demo_table.lance",
  "properties": {"key": "value"}
}

4.3.6 Delete a table

• Method: POST
• Path: /lance/v1/table/{id}/drop

Caution: This operation may delete both metadata and underlying data files. Please make sure to confirm the scope of impact. LAS Catalog does not delete actual data by default.

Input parameters

Request example

curl --location --request POST "${LANCE_BASE}/v1/table/demo_catalog%24demo_schema%24demo_table/drop" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}"

Response example (200)

{
  "id": ["demo_catalog", "demo_schema", "demo_table"],
  "location": "tos://{bucket}/{prefix}/demo_table.lance",
  "properties": {"key": "value"}
}

5. Frequently asked questions (FAQ) #

5.1 Returns 401 / Unauthorized #

• Check whether Authorization/X-Date is correctly generated according to the Volcano Engine signature algorithm
• Check whether Region matches the server Region
• If a gateway/reverse proxy is used, ensure that the host in the signature matches the actual request host

5.2 Created successfully but cannot be queried #

• Check whether {id} is correctly concatenated and URL encoded (especially $, @, #)
• Check whether the correct Endpoint and path prefix are accessed (whether an additional /gravitino-lance is needed)