Help Center/ DataArts Lake Formation/ API Reference/ API/ LakeCat/ Table Management/ Creating a Table

Updated on 2024-02-21 GMT+08:00

View PDF

Creating a Table

Function

This API is used to create a table.

URI

POST /v1/{project_id}/instances/{instance_id}/catalogs/{catalog_name}/databases/{database_name}/tables

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For how to obtain the project ID, see Obtaining a Project ID (lakeformation_04_0026.xml).
instance_id	Yes	String	LakeFormation instance ID. The value is automatically generated when the instance is created, for example, 2180518f-42b8-4947-b20b-adfc53981a25.
catalog_name	Yes	String	Catalog name. The value should contain 1 to 256 characters. Only letters, numbers, and underscores (_) are allowed.
database_name	Yes	String	Database name. The value should contain 1 to 128 characters. Only letters, numbers, hyphens (-), and underscores (_) are allowed.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	Array of strings	Tenant token.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
table_name	Yes	String	Table name. The value should contain 1 to 256 characters. Only letters, numbers, hyphens (-), and underscores (_) are allowed.
table_type	Yes	String	Table type. The options are MANAGED_TABLE (internal tables), EXTERNAL_TABLE (foreign tables), VIRTUAL_VIEW (views), MATERIALIZED_VIEW (materialized views), and DICTIONARY_TABLE (dictionary tables). Enumeration values: MANAGED_TABLE EXTERNAL_TABLE VIRTUAL_VIEW MATERIALIZED_VIEW DICTIONARY_TABLE
owner	No	String	Table owner. Enter 1 to 49 characters. Only letters, numbers, and underscores (_) are allowed.
owner_type	No	String	Owner type. The options are USER (user), GROUP (group), and ROLE (role). Enumeration values: USER GROUP ROLE
create_time	No	String	Table creation time.
last_access_time	No	String	Last access time.
last_analyzed_time	No	String	Last analyzed time.
partition_keys	No	Array of Column objects	Information about partition columns.
retention	No	Integer	Table retention period.
storage_descriptor	Yes	StorageDescriptor object	Data storage.
parameters	No	Map<String,String>	Table parameter information. Each key is a string that contains at least 1 byte but no more than 255 bytes. Each value is a UTF-8 string containing a maximum of 4000 bytes.
comments	No	String	Table description. Enter a maximum of 4,000 characters when you create the table.
view_expanded_text	No	String	If the table type is set to view, the value of this parameter is the extended text of a view; otherwise, the value is null.
view_original_text	No	String	If the table type is set to view, the value of this parameter is the original text of a view; otherwise, the value is null.
ignore_obs_checked	No	Boolean	Whether to ignore the restriction on the OBS path when creating an internal table.
external_table_id	No	String	User table ID, which is specified during creation and cannot be changed.

**Table 4** StorageDescriptor
Parameter	Mandatory	Type	Description
columns	Yes	Array of Column objects	All fields except partition columns.
location	No	String	Path, for example, obs://location/uri/.
compressed	Yes	Boolean	Whether to enable data compression. The default value is false.
input_format	No	String	Input format.
output_format	No	String	Output format.
number_of_buckets	No	Integer	Number of buckets. The default value is 0.
bucket_columns	No	Array of strings	Bucket field.
sort_columns	No	Array of Order objects	A list that specifies the bucket sorting method.
serde_info	Yes	SerDeInfo object	Serialization/Deserialization information.
parameters	Yes	Map<String,String>	Descriptor storage parameter. key can contain 255 characters at most. value can contain a maximum of 4,000 characters.
skewed_info	No	SkewedInfo object	Information about values (skewed values) that often appear in a column.
stored_as_sub_directories	No	Boolean	Whether to store data in subdirectories.

**Table 5** Column
Parameter	Mandatory	Type	Description
column_type	Yes	String	Column type, including array, bigint, binary, boolean, char, date, decimal, double, float, int, interval, map, set, smallint, string, struct, timestamp, tinyint, union, and varchar.
column_name	Yes	String	Column name. The value can contain 1 to 767 characters. Only letters, digits, and special characters (_-+*(),) are allowed.
comment	No	String	Description of a column. Enter a maximum of 4,000 characters.

**Table 6** Order
Parameter	Mandatory	Type	Description
column	No	String	Column name. The value can contain 1 to 767 characters. Only letters, digits, and special characters (_-+*(),) are allowed.
sort_order	No	Integer	Sorting method. The values are ==1 (ascending order) and ==0 (descending order).

**Table 7** SerDeInfo
Parameter	Mandatory	Type	Description
name	No	String	Names.
serialization_library	No	String	Class that implements serialization/deserialization.
parameters	No	Map<String,String>	Parameters. The value of key ranges from 1 to 255. The maximum value of value is 4000.

**Table 8** SkewedInfo
Parameter	Mandatory	Type	Description
skewed_column_names	Yes	Array of strings	List of skewed columns.
skewed_column_value_location_maps	Yes	Map<String,String>	Mapping between skew values and addresses.
skewed_column_values	Yes	Array<Array<String>>	List of skewed values.

Response Parameters

Status code: 201

**Table 9** Response body parameters
Parameter	Type	Description
catalog_name	String	Catalog name.
catalog_id	String	catalogID.
database_name	String	Database name.
database_id	String	Database ID.
table_name	String	Table name.
table_id	String	Table ID.
table_status	Integer	Table status. The options are 0 (normal), 1 (deleted), 2 (restoring).
external_table_id	String	User table ID, which is specified during creation and cannot be changed.
create_time	String	Table creation time.
last_access_time	String	Last access time.
update_time	String	Table metadata last modification time.
last_analyzed_time	String	Last time when column-level statistics were calculated.
owner	String	User information.
owner_type	String	User type. The options are USER (user), GROUP (group), and ROLE (role). Enumeration values: USER GROUP ROLE
parameters	Map<String,String>	Parameter.
partition_keys	Array of Column objects	List of table partition columns.
retention	Integer	Table retention period.
storage_descriptor	StorageDescriptor object	Data storage.
table_type	String	Table type. The options are MANAGED_TABLE (internal tables), EXTERNAL_TABLE (foreign tables), VIRTUAL_VIEW (views), MATERIALIZED_VIEW (materialized views), and DICTIONARY_TABLE (dictionary tables). Enumeration values: MANAGED_TABLE EXTERNAL_TABLE VIRTUAL_VIEW MATERIALIZED_VIEW DICTIONARY_TABLE
comments	String	Table description.
view_expanded_text	String	If the table type is set to view, the value of this parameter is the extended text of a view; otherwise, the value is null.
view_original_text	String	If the table type is set to view, the value of this parameter is the original text of a view; otherwise, the value is null.

**Table 10** StorageDescriptor
Parameter	Type	Description
columns	Array of Column objects	All fields except partition columns.
location	String	Path, for example, obs://location/uri/.
compressed	Boolean	Whether to enable data compression. The default value is false.
input_format	String	Input format.
output_format	String	Output format.
number_of_buckets	Integer	Number of buckets. The default value is 0.
bucket_columns	Array of strings	Bucket field.
sort_columns	Array of Order objects	A list that specifies the bucket sorting method.
serde_info	SerDeInfo object	Serialization/Deserialization information.
parameters	Map<String,String>	Descriptor storage parameter. key can contain 255 characters at most. value can contain a maximum of 4,000 characters.
skewed_info	SkewedInfo object	Information about values (skewed values) that often appear in a column.
stored_as_sub_directories	Boolean	Whether to store data in subdirectories.

**Table 11** Column
Parameter	Type	Description
column_type	String	Column type, including array, bigint, binary, boolean, char, date, decimal, double, float, int, interval, map, set, smallint, string, struct, timestamp, tinyint, union, and varchar.
column_name	String	Column name. The value can contain 1 to 767 characters. Only letters, digits, and special characters (_-+*(),) are allowed.
comment	String	Description of a column. Enter a maximum of 4,000 characters.

**Table 12** Order
Parameter	Type	Description
column	String	Column name. The value can contain 1 to 767 characters. Only letters, digits, and special characters (_-+*(),) are allowed.
sort_order	Integer	Sorting method. The values are ==1 (ascending order) and ==0 (descending order).

**Table 13** SerDeInfo
Parameter	Type	Description
name	String	Names.
serialization_library	String	Class that implements serialization/deserialization.
parameters	Map<String,String>	Parameters. The value of key ranges from 1 to 255. The maximum value of value is 4000.

**Table 14** SkewedInfo
Parameter	Type	Description
skewed_column_names	Array of strings	List of skewed columns.
skewed_column_value_location_maps	Map<String,String>	Mapping between skew values and addresses.
skewed_column_values	Array<Array<String>>	List of skewed values.

Status code: 400

**Table 15** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.
solution_msg	String	Solution.

Status code: 404

**Table 16** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.
solution_msg	String	Solution.

Status code: 500

**Table 17** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.
solution_msg	String	Solution.

Example Requests

POST https://{endpoint} /v1/{project_id}/instances/{instance_id}/catalogs/{catalog_name}/databases/{database_name}/tables

{
  "table_name" : "tbl86b03ad314fa4ea7943fb769df163a79",
  "table_type" : "MANAGED_TABLE",
  "owner" : "onebox",
  "owner_type" : "USER",
  "create_time" : "2023-05-31T01:59:54.000+00:00",
  "last_access_time" : "2023-05-31T01:59:54.000+00:00",
  "last_analyzed_time" : "2023-05-31T01:59:54.000+00:00",
  "partition_keys" : [ {
    "column_type" : "string",
    "column_name" : "column_prefix0",
    "comment" : "5456ac36c75947eab223476dafa58ae0"
  }, {
    "column_type" : "string",
    "column_name" : "column_prefix1",
    "comment" : "d95d1241557e4a769bfcda42974fdf0e"
  } ],
  "retention" : 1000,
  "storage_descriptor" : {
    "columns" : [ {
      "column_type" : "string",
      "column_name" : "column_prefix0",
      "comment" : "3eb10da96ec84ec6b8543b730c0660b2"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix1",
      "comment" : "ee5aa1f3755f425a964f045f59b2c0a0"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix2",
      "comment" : "d47884f69582432db1256e60a8e37ea6"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix3",
      "comment" : "4e26e910310648f1a97b6e17cb2b25ce"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix4",
      "comment" : "85084620943b4d36a9e5d6a856307e73"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix5",
      "comment" : "f78264b5d8ab4409a3a05ebb0434424e"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix6",
      "comment" : "45df8ef109374ac6ab9aaa371b29baa7"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix7",
      "comment" : "c006d18cc411429bacc0f0e1eb75f99e"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix8",
      "comment" : "58e1c81b2c0a4c089570106c8bb4461d"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix9",
      "comment" : "32cc797a16f348ebbf5f2e1f85969603"
    } ],
    "location" : "obs://location/test/database/5e2941387d8741afa217677361d0676f",
    "compressed" : false,
    "input_format" : "850fd4c238934dfdaa3006f388d71f9d",
    "output_format" : "740f42961f1146d39abe19beadc2ad89",
    "number_of_buckets" : 0,
    "bucket_columns" : [ ],
    "sort_columns" : [ ],
    "serde_info" : {
      "name" : "a247cc09ce74477e8c95915bb45e9878",
      "serialization_library" : "9dad2d1dfe944e1d83747997188ed445",
      "parameters" : {
        "347f5f03fdaf46489a39e308be3d2160" : "317b872caa5d4de7bed96f644028ed83"
      }
    },
    "parameters" : {
      "ce43c3c8b9854b749dddabe76c487dd8" : "67393e5c0dc649479399603f6adf1432",
      "8805af26461e49feaf5fb67eef8da574" : "f956a8ac29514f57af9da84043b845f0"
    },
    "skewed_info" : {
      "skewed_column_names" : [ ],
      "skewed_column_value_location_maps" : { },
      "skewed_column_values" : [ ]
    },
    "stored_as_sub_directories" : false
  },
  "parameters" : {
    "key1" : "value1",
    "transient_lastDdlTime" : "120",
    "classification" : "other"
  },
  "comments" : "comment info"
}

Example Responses

Status code: 201

Created

{
  "catalog_name" : "catcd6359b2a15f42dc90fca897c15db00a",
  "database_name" : "dbbf565489e3d04b2d8ca03d6e3d48486f",
  "table_name" : "tbl1298911dffa94c449a900ec5dfc50cf8",
  "create_time" : "2023-05-31T02:03:44.016+00:00",
  "last_access_time" : "2023-05-31T02:03:43.000+00:00",
  "update_time" : "2023-05-31T02:03:44.016+00:00",
  "last_analyzed_time" : "2023-05-31T02:03:43.000+00:00",
  "owner" : "onebox",
  "owner_type" : "USER",
  "parameters" : {
    "key1" : "value1",
    "transient_lastDdlTime" : "120",
    "classification" : "other"
  },
  "partition_keys" : [ {
    "column_type" : "string",
    "column_name" : "column_prefix0",
    "comment" : "8be09e713e6b46a08b375b662f93e195"
  }, {
    "column_type" : "string",
    "column_name" : "column_prefix1",
    "comment" : "6874d3047a6c494696438fc64d9a0194"
  } ],
  "retention" : 1000,
  "storage_descriptor" : {
    "columns" : [ {
      "column_type" : "string",
      "column_name" : "column_prefix0",
      "comment" : "5a2968f6141c4d40969c935c39b5accc"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix1",
      "comment" : "39ac0d5c26ce47d8948a5ea49a455742"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix2",
      "comment" : "a8d51537564a4042ab3d88a0acfccf83"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix3",
      "comment" : "d541dd8c95bf4d49853ae5563869821e"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix4",
      "comment" : "9955f7831b3b4bdc8a18c2e20b592976"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix5",
      "comment" : "32115b31e61245fd94162f566c6db966"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix6",
      "comment" : "a6d61e1ad9e14a6da94e242607369284"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix7",
      "comment" : "9dd785a2f6744fa2a8c5a64d78147961"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix8",
      "comment" : "60128f0062a949559f0c95f2656812ae"
    }, {
      "column_type" : "string",
      "column_name" : "column_prefix9",
      "comment" : "99d4d3e57af64bd1bb287b5a305b7225"
    } ],
    "location" : "obs://location/test/database/0b288717b41a411dacdd0c9fa2e1c275",
    "compressed" : false,
    "input_format" : "c28e802613a342568a667aeba4961979",
    "output_format" : "9bf425a38fd540c69b68366071b8bbd5",
    "number_of_buckets" : 0,
    "bucket_columns" : [ ],
    "sort_columns" : [ ],
    "serde_info" : {
      "name" : "e044a1458d8c4b7a871e54243d2adb93",
      "serialization_library" : "bb299f2201fe4da0886ecd380a1508a3",
      "parameters" : {
        "2980009b8dfd4b3bb78a96485a3728c2" : "f83395c8db5e4ac1803892b08c209799"
      }
    },
    "parameters" : {
      "64f073b0a9bd49cb8437681f3faa1538" : "f4154f400e6e465cbc8b8b2033a24faf",
      "f31bf1375d4d4097b68e9816388e50a8" : "881546d1b0184048b03ad20d1218104d"
    },
    "skewed_info" : {
      "skewed_column_names" : [ ],
      "skewed_column_value_location_maps" : { },
      "skewed_column_values" : [ ]
    },
    "stored_as_sub_directories" : false
  },
  "table_type" : "EXTERNAL_TABLE",
  "comments" : "comment info"
}

Status code: 400

Bad Request

{
  "error_code" : "common.01000001",
  "error_msg" : "failed to read http request, please check your input, code: 400, reason: Type mismatch., cause: TypeMismatchException"
}

Status code: 401

Unauthorized

{
  "error_code": 'APIG.1002',
  "error_msg": 'Incorrect token or token resolution failed'
}

Status code: 403

Forbidden

{
  "error" : {
    "code" : "403",
    "message" : "X-Auth-Token is invalid in the request",
    "error_code" : null,
    "error_msg" : null,
    "title" : "Forbidden"
  },
  "error_code" : "403",
  "error_msg" : "X-Auth-Token is invalid in the request",
  "title" : "Forbidden"
}

Status code: 404

Not Found

{
  "error_code" : "common.01000001",
  "error_msg" : "response status exception, code: 404"
}

Status code: 408

Request Timeout

{
  "error_code" : "common.00000408",
  "error_msg" : "timeout exception occurred"
}

Status code: 500

Internal Server Error

{
  "error_code" : "common.00000500",
  "error_msg" : "internal error"
}

Status Codes

Status Code	Description
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
408	Request Timeout
500	Internal Server Error

Error Codes

See Error Codes.

Parent topic: Table Management

Previous topic: Listing Tables on Different Pages by Condition

Next topic: Obtaining Table Information

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot