GetTable

Usage notes

Note

This API supports only Iceberg tables, not Lance tables. To query Lance tables, use the Lance REST Namespace API or the Lance ecosystem (Spark, Trino, and other compute engines).

Query a table by name (tableBucketARN, namespace, and name) or by ARN (tableArn). The two methods are mutually exclusive.

Permissions

API	Action	Description
GetTable	oss:GetTable	Retrieves table information. Also checks the table policy. Admin users are exempt.

Request syntax

GET /get-table HTTP/1.1
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request parameters

Parameter	Type	Required	Example value	Description
tableBucketARN	String	No	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket	The Table Bucket ARN. Used with `namespace` and `name` for queries by name. Mutually exclusive with `tableArn`.
namespace	String	No	my_namespace	The namespace of the table. Required for queries by name. Passed in the query string.
name	String	No	my_table	The table name. Required for queries by name. Passed in the query string.
tableArn	String	No	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table_id	The table ARN. Required for queries by ARN. Passed in the query string. Mutually exclusive with `tableBucketARN`, `namespace`, and `name`.

Response parameters

Parameter	Type	Example value	Description
name	String	my_table	The name of the table.
namespace	Array	-	Array of namespace names where the table resides.
tableARN	String	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table-id	The ARN of the table.
format	String	ICEBERG	The table format. Valid value: `ICEBERG`.
versionToken	String	abc123def456	Version token for optimistic locking.
metadataLocation	String	oss://bucket/metadata/00000-xxx.metadata.json	OSS path to the table metadata file.
warehouseLocation	String	oss://data-bucket/warehouse/	OSS path to the table warehouse.
type	String	customer	Table type. Valid value: `customer`.
createdAt	String	2024-01-01T00:00:00.000000Z	Table creation time in ISO 8601 format.
createdBy	String	1234567890	Account ID of the table creator.
modifiedAt	String	2024-06-01T00:00:00.000000Z	Last modification time in ISO 8601 format.
modifiedBy	String	1234567890	Account ID of the last modifier.
ownerAccountId	String	1234567890	Account ID of the table owner.
tableBucketId	String	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	ID of the Table Bucket containing the table.
namespaceId	String	ns-xxxxxxxx	ID of the namespace containing the table.

Examples

Request example

GET /get-table?tableBucketARN=acs%3Aosstables%3Acn-hangzhou%3A1234567890%3Abucket%2Fmy-table-bucket&namespace=my_namespace&name=my_table HTTP/1.1
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: Thu, 10 Apr 2025 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/osstables/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c****

Response example

HTTP/1.1 200 OK
Server: AliyunOSS
x-oss-request-id: 5C06A3B67B8B5A3DA422****
x-oss-server-time: 3
Content-Type: application/json


{
   "name": "my_table",
   "namespace": ["my_namespace"],
   "tableARN": "acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table_id",
   "format": "ICEBERG",
   "versionToken": "aaabbb",
   "metadataLocation": "oss://data-bucket/metadata/00000-xxx.metadata.json",
   "warehouseLocation": "oss://data-bucket/warehouse/",
   "type": "customer",
   "createdAt": "2024-01-01T00:00:00.000000Z",
   "createdBy": "1234567890",
   "modifiedAt": "2024-06-01T00:00:00.000000Z",
   "modifiedBy": "1234567890",
   "ownerAccountId": "1234567890",
   "tableBucketId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "namespaceId": "ns-xxxxxxxx"
}

SDKs

Supported SDKs:

ossutil command-line tool

Equivalent ossutil command: get-table.

Error codes

Error code	HTTP status code	Description
BadRequestException	400	The request is invalid or incorrectly formatted.
ForbiddenException	403	You are not authorized to perform this operation.
NotFoundException	404	The requested resource does not exist.