创建Table-对象存储(OSS)-阿里云帮助中心

注意事项

表名称只能包含小写字母、数字和下划线（_），且必须以小写字母或数字开头和结尾。
同一个Namespace下的表名称不能重复。
--metadata参数需要传入JSON格式的表元数据，定义Iceberg表的Schema。可以通过命令行内联JSON或使用file://指定本地JSON文件。
在iceberg下使用schemaV2，可以定义基础类型，以及struct（结构体）、list（列表）、map（键值映射）和它们的嵌套组合。
原有schema仍可使用。同一次建表请求中，schema和schemaV2必须选择一个，不能同时指定。
目前--format参数仅支持ICEBERG。

命令格式

ossutil tables-api create-table --table-bucket-arn value --namespace value --name value --format value  [flags]

参数	类型	说明
--encryption-configuration	string	表的加密配置，JSON格式。用于指定服务端加密方式。
--format	string	表格式，目前仅支持`ICEBERG`。
--metadata	string	表元数据，JSON格式。通过iceberg.schema或iceberg.schemaV2定义表结构，定义复杂类型时使用schemaV2。支持内联JSON或`file://`本地文件。
--name	string	表名称。只能包含小写字母、数字和下划线。
--namespace	string	表所在的命名空间名称。
--table-bucket-arn	string	Table Bucket的ARN，格式为`acs:osstables:{region}:{uid}:bucket/{bucket-name}`。

说明

create-table命令对应API接口CreateTable。关于API中的具体参数含义，请参见CreateTable。
关于支持的全局命令行选项，请参见ossutil全局选项。

示例1：--metadata参数使用schema建表

{
  "iceberg": {
    "schema": {
      "fields": [
        {
          "id": 1,
          "name": "id",
          "type": "long",
          "required": true
        },
        {
          "id": 2,
          "name": "name",
          "type": "string",
          "required": false
        },
        {
          "id": 3,
          "name": "created_at",
          "type": "timestamp",
          "required": false
        }
      ]
    }
  }
}

其中，每个字段（field）的属性说明如下：

id：字段编号，整数类型，必须唯一且递增。
name：字段名称，字符串类型。
type：字段数据类型，支持long、string、int、boolean、float、double、timestamp等Iceberg支持的类型。
required：是否为必填字段，布尔类型。设置为true表示该字段不允许为空。

如需定义复杂类型或嵌套结构，可在--metadata的JSON中使用iceberg.schemaV2定义表结构。

示例2：--metadata参数使用schemaV2建表

{
  "iceberg": {
    "schemaV2": {
      "type": "struct",
      "fields": [
        {
          "id": 10,
          "name": "order_id",
          "type": "long",
          "required": true
        },
        {
          "id": 20,
          "name": "customer",
          "required": false,
          "type": {
            "type": "struct",
            "fields": [
              {
                "id": 21,
                "name": "name",
                "type": "string",
                "required": false
              },
              {
                "id": 22,
                "name": "level",
                "type": "int",
                "required": false
              }
            ]
          }
        },
        {
          "id": 30,
          "name": "tags",
          "required": false,
          "type": {
            "type": "list",
            "element-id": 31,
            "element": "string",
            "element-required": false
          }
        },
        {
          "id": 40,
          "name": "attributes",
          "required": false,
          "type": {
            "type": "map",
            "key-id": 41,
            "key": "string",
            "value-id": 42,
            "value": "string",
            "value-required": false
          }
        }
      ]
    }
  }
}

其中，schemaV2每个字段的属性说明如下：

id：字段编号，整数类型。字段以及list元素、map键和值的编号不能重复。必填。
name：字段名称。必填。
type：字段数据类型。基础类型使用字符串，例如"long"、"string"；复杂类型使用JSON对象。必填。
required：字段是否允许为null。true表示不允许，false表示允许，默认false。选填。
doc：字段的说明文字。选填。

复杂类型说明如下：

struct：把一组有名称的子字段放在一起，例如客户的姓名和等级。使用fields定义子字段。
list：保存同一种类型的多个元素，例如字符串标签列表。element指定元素类型，element-id指定元素编号，element-required指定元素是否不允许为null。
map：保存键值对，例如属性名和属性值。key和value指定键和值的类型，key-id和value-id指定对应编号，value-required指定值是否不允许为null。键不允许为null。

复杂类型可以继续嵌套，例如list的元素也可以是struct。字段的required控制整个字段是否允许为null；element-required和value-required分别控制列表元素和映射值是否允许为null。

使用示例

在命名空间my_namespace下创建名为my_table的Iceberg表，通过内联JSON指定表的Schema。

ossutil tables-api create-table --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table --format ICEBERG --metadata '{"iceberg":{"schema":{"fields":[{"id":1,"name":"id","type":"long","required":true},{"id":2,"name":"data","type":"string"}]}}}'

通过内联JSON创建包含基础类型的表。使用schemaV2定义字段：id为long类型且不允许为null，name为string类型且允许为null。

ossutil tables-api create-table --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table --format ICEBERG --metadata '{"iceberg":{"schemaV2":{"type":"struct","fields":[{"id":10,"name":"id","type":"long","required":true},{"id":20,"name":"name","type":"string","required":false}]}}}'

通过本地JSON文件创建Iceberg表。将表元数据保存为本地文件table_metadata.json后，通过file://方式指定。

ossutil tables-api create-table --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table --format ICEBERG --metadata file://table_metadata.json