Create a table

Notes

• Table names can contain only lowercase letters, digits, and underscores (_), and must start and end with a lowercase letter or digit.

• Table names must be unique within a namespace.

• The --metadata parameter accepts JSON that defines the Iceberg table schema. Provide JSON inline or reference a local file with the file:// prefix.

• You can use schemaV2 under iceberg to define primitive types and struct, list, and map types, including nested combinations of these types.

• The original schema parameter remains available. In a single table creation request, you must specify either schema or schemaV2, but not both.

• The --format parameter supports only ICEBERG.

Syntax

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

Example 1: Create a table by using schema in --metadata

{
  "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 attributes:

• id: Unique incremental integer.

• name: Field name.

• type: Data type. Supported types: long, string, int, boolean, float, double, and timestamp.

• required: Whether the field is required. If true, the field cannot be null.

To define complex or nested types, use iceberg.schemaV2 in the JSON of --metadata.

Example 2: Create a table by using schemaV2 in --metadata

{
  "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
          }
        }
      ]
    }
  }
}

Field attributes of schemaV2:

• id: Required integer. The ID of the field. The IDs of fields, list elements, and map keys and values must not duplicate each other.

• name: Required. The field name.

• type: Required. The field data type. Primitive types are strings, such as "long" and "string". Complex types are JSON objects.

• required: Optional. Whether the field can be null. true indicates that the field cannot be null, and false indicates that the field can be null. Default value: false.

• doc: Optional. The description of the field.

Complex types:

• struct: groups multiple named sub-fields, such as the name and level of a customer. Use fields to define the sub-fields.

• list: stores multiple elements of the same type, such as a list of string tags. element specifies the element type, element-id specifies the element ID, and element-required specifies whether the elements cannot be null.

• map: stores key-value pairs, such as attribute names and values. key and value specify the types of the keys and values, key-id and value-id specify their IDs, and value-required specifies whether the values cannot be null. Keys cannot be null.

Complex types can be nested. For example, the element of a list can be a struct. The required attribute of a field controls whether the entire field can be null, whereas element-required and value-required control whether list elements and map values can be null.

Examples

• Create an Iceberg table named my_table in the my_namespace namespace with an inline 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"}]}}}'

• Create a table that contains only primitive types by using inline JSON. In this example, schemaV2 defines the fields: id is of the LONG type and cannot be null, and name is of the STRING type and can be 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}]}}}'

• Create an Iceberg table from a local JSON metadata file. Save the schema to table_metadata.json, then reference it with the file:// prefix.

  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