<a id="cli-aws-s3tables-create-table"></a>

# create-table

## Description

Creates a new table associated with the given namespace in a table bucket. For more information, see [Creating an Amazon S3 table](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-create.html) in the *Amazon Simple Storage Service User Guide* .

> Permissions
* You must have the `s3tables:CreateTable` permission to use this operation.
* If you use this operation with the optional `metadata` request parameter you must have the `s3tables:PutTableData` permission.
* If you use this operation with the optional `encryptionConfiguration` request parameter you must have the `s3tables:PutTableEncryption` permission.
* If you use this operation with the `storageClassConfiguration` request parameter, you must have the `s3tables:PutTableStorageClass` permission.
* To create a table with tags, you must have the `s3tables:TagResource` permission in addition to `s3tables:CreateTable` permission.

#### NOTE
Additionally, If you choose SSE-KMS encryption you must grant the S3 Tables maintenance principal access to your KMS key. For more information, see [Permissions requirements for S3 Tables SSE-KMS encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-kms-permissions.html) .

See also: [AWS API Documentation](https://docs.aws.amazon.com/goto/WebAPI/s3tables-2018-05-10/CreateTable)

`create-table` uses document type values. Document types follow the JSON data model where valid values are: strings, numbers, booleans, null, arrays, and objects. For command input, options and nested parameters that are labeled with the type `document` must be provided as JSON. Shorthand syntax does not support document types.

## Synopsis

```
  create-table
--table-bucket-arn <value>
--namespace <value>
--name <value>
--format <value>
[--metadata <value>]
[--encryption-configuration <value>]
[--storage-class-configuration <value>]
[--tags <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]
[--cli-error-format <value>]
```

## Options

`--table-bucket-arn` (string) [required]

> The Amazon Resource Name (ARN) of the table bucket to create the table in.

> Constraints:

> * pattern: `(arn:aws[-a-z0-9]*:[a-z0-9]+:[-a-z0-9]*:[0-9]{12}:bucket/[a-z0-9_-]{3,63})`

`--namespace` (string) [required]

> The namespace to associated with the table.

> Constraints:

> * min: `1`
> * max: `255`
> * pattern: `[0-9a-z_]*`

`--name` (string) [required]

> The name for the table.

> Constraints:

> * min: `1`
> * max: `255`
> * pattern: `[0-9a-z_]*`

`--format` (string) [required]

> The format for the table.

> Possible values:

> * `ICEBERG`

`--metadata` (tagged union structure)

> The metadata for the table.

> #### NOTE
> This is a Tagged Union structure. Only one of the following top level keys can be set: `iceberg`.

> iceberg -> (structure)

> > Contains details about the metadata of an Iceberg table.

> > schema -> (structure)

> > > The schema for an Iceberg table. Use this property to define table schemas with primitive types only. For schemas that include nested or complex types such as `struct` , `list` , or `map` , use `schemaV2` instead.

> > > fields -> (list) [required]

> > > > The schema fields for the table

> > > > (structure)

> > > > > Contains details about a schema field.

> > > > > id -> (integer)

> > > > > > An optional unique identifier for the schema field. Field IDs are used by Apache Iceberg to track schema evolution and maintain compatibility across schema changes. If not specified, S3 Tables automatically assigns field IDs.

> > > > > name -> (string) [required]

> > > > > > The name of the field.

> > > > > type -> (string) [required]

> > > > > > The field type. S3 Tables supports all Apache Iceberg primitive types. For more information, see the [Apache Iceberg documentation](https://iceberg.apache.org/spec/#primitive-types) .

> > > > > required -> (boolean)

> > > > > > A Boolean value that specifies whether values are required for each row in this field. By default, this is `false` and null values are allowed in the field. If this is `true` the field does not allow null values.

> > schemaV2 -> (structure)

> > > The schema for an Iceberg table using the V2 format. Use this property to define table schemas that include nested or complex data types such as `struct` , `list` , or `map` , in addition to primitive types. For schemas with only primitive types, you can use either `schema` or `schemaV2` .

> > > type -> (string) [required]

> > > > The type of the top-level schema, which is always a `struct` type as defined in the [Apache Iceberg specification](https://iceberg.apache.org/spec/#schemas-and-data-types) . This value must be `struct` .

> > > > Possible values:

> > > > * `struct`

> > > fields -> (list) [required]

> > > > The schema fields for the table. Each field defines a column in the table, including its name, type, and whether it is required.

> > > > (structure)

> > > > > Contains details about a schema field in the V2 format. This field format supports nested and complex data types such as `struct` , `list` , and `map` , in addition to primitive types.

> > > > > id -> (integer) [required]

> > > > > > The unique identifier for the schema field. Field IDs are used by Apache Iceberg to track schema evolution and maintain compatibility across schema changes.

> > > > > name -> (string) [required]

> > > > > > The name of the field.

> > > > > type -> (document) [required]

> > > > > > The data type of the field. This can be a primitive type string such as `boolean` , `int` , `long` , `float` , `double` , `string` , `binary` , `date` , `timestamp` , or `timestamptz` , or a complex type represented as a JSON object for nested types such as `struct` , `list` , or `map` . For more information, see the [Apache Iceberg schemas and data types documentation](https://iceberg.apache.org/spec/#schemas-and-data-types) .

> > > > > required -> (boolean) [required]

> > > > > > A Boolean value that specifies whether values are required for each row in this field. If this is `true` , the field does not allow null values.

> > > > > doc -> (string)

> > > > > > An optional description of the field.

> > > schemaId -> (integer)

> > > > An optional unique identifier for the schema. Schema IDs are used by Apache Iceberg to track schema evolution.

> > > identifierFieldIds -> (list)

> > > > A list of field IDs that are used as the identifier fields for the table. Identifier fields uniquely identify a row in the table.

> > > > (integer)

> > partitionSpec -> (structure)

> > > The partition specification for the Iceberg table. Partitioning organizes data into separate files based on the values of one or more fields, which can improve query performance by reducing the amount of data scanned. Each partition field applies a transform (such as identity, year, month, or bucket) to a single field.

> > > fields -> (list) [required]

> > > > The list of partition fields that define how the table data is partitioned. Each field specifies a source field and a transform to apply. This field is required if `partitionSpec` is provided.

> > > > (structure)

> > > > > Defines a single partition field in an Iceberg partition specification.

> > > > > sourceId -> (integer) [required]

> > > > > > The ID of the source schema field to partition by. This must reference a valid field ID from the table schema.

> > > > > transform -> (string) [required]

> > > > > > The partition transform to apply to the source field. Supported transforms include `identity` , `year` , `month` , `day` , `hour` , `bucket` , and `truncate` . For more information, see the [Apache Iceberg partition transforms documentation](https://iceberg.apache.org/spec/#partition-transforms) .

> > > > > name -> (string) [required]

> > > > > > The name for this partition field. This name is used in the partitioned file paths.

> > > > > fieldId -> (integer)

> > > > > > An optional unique identifier for this partition field. If not specified, S3 Tables automatically assigns a field ID.

> > > specId -> (integer)

> > > > The unique identifier for this partition specification. If not specified, defaults to `0` .

> > writeOrder -> (structure)

> > > The sort order for the Iceberg table. Sort order defines how data is sorted within data files, which can improve query performance by enabling more efficient data skipping and filtering.

> > > orderId -> (integer) [required]

> > > > The unique identifier for this sort order. If not specified, defaults to `1` . The order ID is used by Apache Iceberg to track sort order evolution.

> > > fields -> (list) [required]

> > > > The list of sort fields that define how data is sorted within files. Each field specifies a source field, sort direction, and null ordering. This field is required if `writeOrder` is provided.

> > > > (structure)

> > > > > Defines a single sort field in an Iceberg sort order specification.

> > > > > sourceId -> (integer) [required]

> > > > > > The ID of the source schema field to sort by. This must reference a valid field ID from the table schema.

> > > > > transform -> (string) [required]

> > > > > > The transform to apply to the source field before sorting. Use `identity` to sort by the field value directly, or specify other transforms as needed.

> > > > > direction -> (string) [required]

> > > > > > The sort direction. Valid values are `asc` for ascending order or `desc` for descending order.

> > > > > > Possible values:

> > > > > > * `asc`
> > > > > > * `desc`

> > > > > nullOrder -> (string) [required]

> > > > > > Specifies how null values are ordered. Valid values are `nulls-first` to place nulls before non-null values, or `nulls-last` to place nulls after non-null values.

> > > > > > Possible values:

> > > > > > * `nulls-first`
> > > > > > * `nulls-last`

> > properties -> (map)

> > > A map of custom configuration properties for the Iceberg table.

> > > key -> (string)

> > > value -> (string)

JSON Syntax:

```json
{
  "iceberg": {
    "schema": {
      "fields": [
        {
          "id": integer,
          "name": "string",
          "type": "string",
          "required": true|false
        }
        ...
      ]
    },
    "schemaV2": {
      "type": "struct",
      "fields": [
        {
          "id": integer,
          "name": "string",
          "type": {...},
          "required": true|false,
          "doc": "string"
        }
        ...
      ],
      "schemaId": integer,
      "identifierFieldIds": [integer, ...]
    },
    "partitionSpec": {
      "fields": [
        {
          "sourceId": integer,
          "transform": "string",
          "name": "string",
          "fieldId": integer
        }
        ...
      ],
      "specId": integer
    },
    "writeOrder": {
      "orderId": integer,
      "fields": [
        {
          "sourceId": integer,
          "transform": "string",
          "direction": "asc"|"desc",
          "nullOrder": "nulls-first"|"nulls-last"
        }
        ...
      ]
    },
    "properties": {"string": "string"
      ...}
  }
}
```

`--encryption-configuration` (structure)

> The encryption configuration to use for the table. This configuration specifies the encryption algorithm and, if using SSE-KMS, the KMS key to use for encrypting the table.

> #### NOTE
> If you choose SSE-KMS encryption you must grant the S3 Tables maintenance principal access to your KMS key. For more information, see [Permissions requirements for S3 Tables SSE-KMS encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-kms-permissions.html) .

> sseAlgorithm -> (string) [required]

> > The server-side encryption algorithm to use. Valid values are `AES256` for S3-managed encryption keys, or `aws:kms` for Amazon Web Services KMS-managed encryption keys. If you choose SSE-KMS encryption you must grant the S3 Tables maintenance principal access to your KMS key. For more information, see [Permissions requirements for S3 Tables SSE-KMS encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-kms-permissions.html) .

> > Possible values:

> > * `AES256`
> > * `aws:kms`

> kmsKeyArn -> (string)

> > The Amazon Resource Name (ARN) of the KMS key to use for encryption. This field is required only when `sseAlgorithm` is set to `aws:kms` .

> > Constraints:

> > * min: `1`
> > * max: `2048`
> > * pattern: `(arn:aws[-a-z0-9]*:kms:[-a-z0-9]*:[0-9]{12}:key/.+)`

Shorthand Syntax:

```
sseAlgorithm=string,kmsKeyArn=string
```

JSON Syntax:

```json
{
  "sseAlgorithm": "AES256"|"aws:kms",
  "kmsKeyArn": "string"
}
```

`--storage-class-configuration` (structure)

> The storage class configuration for the table. If not specified, the table inherits the storage class configuration from its table bucket. Specify this parameter to override the bucket’s default storage class for this table.

> storageClass -> (string) [required]

> > The storage class for the table or table bucket. Valid values include storage classes optimized for different access patterns and cost profiles.

> > Possible values:

> > * `STANDARD`
> > * `INTELLIGENT_TIERING`

Shorthand Syntax:

```
storageClass=string
```

JSON Syntax:

```json
{
  "storageClass": "STANDARD"|"INTELLIGENT_TIERING"
}
```

`--tags` (map)

> A map of user-defined tags that you would like to apply to the table that you are creating. A tag is a key-value pair that you apply to your resources. Tags can help you organize, track costs for, and control access to resources. For more information, see [Tagging for cost allocation or attribute-based access control (ABAC)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/tagging.html) .

> #### NOTE
> You must have the `s3tables:TagResource` permission in addition to `s3tables:CreateTable` permission to create a table with tags.

> key -> (string)

> > Constraints:

> > * min: `1`
> > * max: `128`

> value -> (string)

> > Constraints:

> > * min: `0`
> > * max: `256`

Shorthand Syntax:

```
KeyName1=string,KeyName2=string
```

JSON Syntax:

```json
{"string": "string"
  ...}
```

`--cli-input-json` | `--cli-input-yaml` (string)
Reads arguments from the JSON string provided. The JSON string follows the format provided by `--generate-cli-skeleton`. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with `--cli-input-yaml`.

`--generate-cli-skeleton` (string)
Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value `input`, prints a sample input JSON that can be used as an argument for `--cli-input-json`. Similarly, if provided `yaml-input` it will print a sample input YAML that can be used with `--cli-input-yaml`. If provided with the value `output`, it validates the command inputs and returns a sample output JSON for that command. The generated JSON skeleton is not stable between versions of the AWS CLI and there are no backwards compatibility guarantees in the JSON skeleton generated.

## Global Options

`--debug` (boolean)

Turn on debug logging.

`--endpoint-url` (string)

Override command’s default URL with the given URL.

`--no-verify-ssl` (boolean)

By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.

`--no-paginate` (boolean)

Disable automatic pagination. If automatic pagination is disabled, the AWS CLI will only make one call, for the first page of results.

`--output` (string)

The formatting style for command output.

* json
* text
* table
* yaml
* yaml-stream
* off

`--query` (string)

A JMESPath query to use in filtering the response data.

`--profile` (string)

Use a specific profile from your credential file.

`--region` (string)

The region to use. Overrides config/env settings.

`--version` (string)

Display the version of this tool.

`--color` (string)

Turn on/off color output.

* on
* off
* auto

`--no-sign-request` (boolean)

Do not sign requests. Credentials will not be loaded if this argument is provided.

`--ca-bundle` (string)

The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.

`--cli-read-timeout` (int)

The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.

`--cli-connect-timeout` (int)

The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.

`--cli-binary-format` (string)

The formatting style to be used for binary blobs. The default format is base64. The base64 format expects binary blobs to be provided as a base64 encoded string. The raw-in-base64-out format preserves compatibility with AWS CLI V1 behavior and binary values must be passed literally. When providing contents from a file that map to a binary blob `fileb://` will always be treated as binary and use the file contents directly regardless of the `cli-binary-format` setting. When using `file://` the file contents will need to properly formatted for the configured `cli-binary-format`.

* base64
* raw-in-base64-out

`--no-cli-pager` (boolean)

Disable cli pager for output.

`--cli-auto-prompt` (boolean)

Automatically prompt for CLI input parameters.

`--no-cli-auto-prompt` (boolean)

Disable automatically prompt for CLI input parameters.

`--cli-error-format` (string)

The formatting style for error output. By default, errors are displayed in enhanced format.

* legacy
* json
* yaml
* text
* table
* enhanced

## Output

tableARN -> (string)

> The Amazon Resource Name (ARN) of the table.

> Constraints:

> * min: `1`
> * max: `2048`
> * pattern: `(arn:aws[-a-z0-9]*:[a-z0-9]+:[-a-z0-9]*:[0-9]{12}:bucket/[a-z0-9_-]{3,63}/table/[a-zA-Z0-9-_]{1,255})`

versionToken -> (string)

> The version token of the table.

> Constraints:

> * min: `1`
> * max: `2048`