Create a table (HTTP)

For details about additional languages, see:

Tables with the Data API are currently in public preview. Development is ongoing, and the features and functionality are subject to change. Hyper-Converged Database (HCD), and the use of such, is subject to the DataStax Preview Terms.

Creates a new table in a keyspace in a database.

After you create a table, index columns that you want to sort or filter. This optimizes your queries and avoids resource intensive, long running allow filtering operations.

You can also modify the table columns later. To add data to your table, insert rows.

Ready to write code? See the examples for this method to get started.

Result

Creates a table with the specified parameters.

If the command succeeds, the response indicates the success.

Example successful response:

{
  "status": {
    "ok": 1
  }
}

Signature

Use the createTable command.

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "createTable": {
    "name": "TABLE_NAME",
    "definition": {
      "columns": {
        "COLUMN_NAME": "DATA_TYPE",
        "COLUMN_NAME": "DATA_TYPE"
      },
      "primaryKey": "PRIMARY_KEY_DEFINITION"
    }
  }
}'

Parameters

Name Type Summary

Name	Type	Summary
`name`	`string`	The name of the table. Table names must follow these rules: Can contain letters, numbers, and underscores Cannot exceed 48 characters Must be unique within the keyspace
`definition`	`object`	The full schema for the table, including column names, column data types, and the primary key. See the examples for usage. See Properties of `definition` for more details.

name

string

The name of the table.

Table names must follow these rules:

Can contain letters, numbers, and underscores
Cannot exceed 48 characters
Must be unique within the keyspace

definition

object

The full schema for the table, including column names, column data types, and the primary key.

See the examples for usage. See Properties of definition for more details.

Properties of `definition`
Name	Type	Summary
`columns`	`object`	The column names and data types. All column names must be unique within the table. See the examples for usage.
`primaryKey`	`string` \| `object`	The primary key for the table. See the examples for usage.

Examples

The following examples demonstrate how to create a table.

Create a table with a single-column primary key

A single-column primary key is a primary key consisting of one column. For more information, see Primary keys in tables (HTTP).

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createTable": {
    "name": "example_table",
    "definition": {
      "columns": {
        "title": {
          "type": "text"
        },
        "number_of_pages": {
          "type": "int"
        },
        "rating": {
          "type": "float"
        },
        "metadata": {
          "type": "map",
          "keyType": "text",
          "valueType": "text"
        },
        "genres": {
          "type": "set",
          "valueType": "text"
        },
        "is_checked_out": {
          "type": "boolean"
        },
        "due_date": {
          "type": "date"
        }
      },
      "primaryKey": "title"
    }
  }
}'

Create a table with a composite primary key

A composite primary key is a primary key consisting of multiple columns. For more information, see Primary keys in tables (HTTP).

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createTable": {
    "name": "example_table",
    "definition": {
      "columns": {
        "title": {
          "type": "text"
        },
        "number_of_pages": {
          "type": "int"
        },
        "rating": {
          "type": "float"
        },
        "metadata": {
          "type": "map",
          "keyType": "text",
          "valueType": "text"
        },
        "genres": {
          "type": "set",
          "valueType": "text"
        },
        "is_checked_out": {
          "type": "boolean"
        },
        "due_date": {
          "type": "date"
        }
      },
      "primaryKey": {
        "partitionBy": [
          "title", "rating"
        ]
      }
    }
  }
}'

Create a table with a compound primary key

A compound primary key is a primary key consisting of partition (grouping) columns and clustering (sorting) columns. For more information, see Primary keys in tables (HTTP).

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createTable": {
    "name": "example_table",
    "definition": {
      "columns": {
        "title": {
          "type": "text"
        },
        "number_of_pages": {
          "type": "int"
        },
        "rating": {
          "type": "float"
        },
        "metadata": {
          "type": "map",
          "keyType": "text",
          "valueType": "text"
        },
        "genres": {
          "type": "set",
          "valueType": "text"
        },
        "is_checked_out": {
          "type": "boolean"
        },
        "due_date": {
          "type": "date"
        }
      },
      "primaryKey": {
        "partitionBy": [
          "title",
          "rating"
        ],
        "partitionSort": {
          "number_of_pages": 1,
          "is_checked_out": -1
        }
      }
    }
  }
}'

Create a table with a column to store vector embeddings

If you want to store pre-generated vector embeddings in a table, create a table with a vector column. A table can include more than one vector column.

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createTable": {
    "name": "example_table",
    "definition": {
      "columns": {
        "example_vector": {
          "type": "vector",
          "dimension": 1024
        },
        "example_non_vector": {
          "type": "text"
        }
      },
      "primaryKey": "example_non_vector"
    }
  }
}'

Create a table (HTTP)

Result

Signature

Parameters

Examples

Create a table with a single-column primary key

Create a table with a composite primary key

Create a table with a compound primary key

Create a table with a column to store vector embeddings

Was this helpful?

Give Feedback