Create an index

Creates a new index for a column in a table in a database.

You should index any column that you want to sort or filter on. Columns that are part of the primary key are automatically indexed.

To create an index on a vector column, see Create a vector index instead.

To index a text column for lexicographical matching, see Create an index instead.

To manage indexes, your application token must have the same level of permissions that you need to manage tables.

Ready to write code? See the examples for this method to get started. If you are new to the Data API, check out the quickstart.

Result

  • Python

  • TypeScript

  • Java

  • curl

Creates an index for the specified column.

Does not return anything.

Creates an index for the specified column.

Returns a promise that resolves once the operation completes.

Creates an index for the specified column.

Does not return anything.

Creates an index for the specified column.

If the command succeeds, the response indicates the success.

Example response:

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

Parameters

  • Python

  • TypeScript

  • Java

  • curl

Use the create_index method, which belongs to the astrapy.Table class.

Method signature
create_index(
  name: str,
  column: str | dict[str, str],
  *,
  definition: TableIndexDefinition | dict[str, Any],
  options: TableIndexOptions | dict[str, Any],
  if_not_exists: bool,
  table_admin_timeout_ms: int,
  request_timeout_ms: int,
  timeout_ms: int,
) -> None
Name Type Summary

name

str

The name of the index.

Index names for tables must follow these rules:

  • Must be unique within the keyspace

  • Can contain letters, numbers, and underscores

  • Must have a length of 1 to 100 characters

column

str

The name of the table column on which to create the index.

The column name must use snake case, not camel case.

For map columns, you can index the entries, only the keys, or only the values. See Create an index for a map column for an example.

To create vector indexes based on vector columns, see Create a vector index.

definition

TableIndexDefinition | dict

Optional. Specifies the indexed column and index options. If you use this parameter, the column and options parameters are not accepted.

options

TableIndexOptions | dict

if_not_exists

bool

Optional. Whether the command should silently succeed even if an index with the given name already exists in the keyspace and no new index was created.

This option only checks index names. It does not check index definitions.

Default: false

table_admin_timeout_ms

int

Optional. A timeout, in milliseconds, to impose on the underlying API request. If not provided, the Table defaults apply.

This parameter is aliased as request_timeout_ms and timeout_ms for convenience.

Use the createIndex method, which belongs to the Table class.

Method signature
async createIndex(
  name: string,
  column: keyof Schema | Partial<Record<keyof Schema, string>>,
  options?: {
    ifNotExists?: boolean,
    options?: {
      ascii?: boolean,
      normalize?: boolean,
      caseSensitive?: boolean,
      timeout?: number | TimeoutDescriptor,
    },
  },
): void
Name Type Summary

name

string

The name of the index.

Index names for tables must follow these rules:

  • Must be unique within the keyspace

  • Can contain letters, numbers, and underscores

  • Must have a length of 1 to 100 characters

column

string

The name of the table column on which to create the index.

The column name must use snake case, not camel case.

For map columns, you can index the entries, only the keys, or only the values. See Create an index for a map column for an example.

To create vector indexes based on vector columns, see Create a vector index.

options

TableCreateIndexOptions

Optional. The options for this operation. See Properties of options for more details.

Properties of options
Name Type Summary

ascii

boolean

Optional. Whether to convert non-ASCII characters to their US-ASCII equivalent before indexing.

For more information, see Index options for text and ASCII types.

See Create an index and specify ASCII conversion before indexing for an example.

Default: false

normalize

boolean

Optional. Whether to normalize Unicode characters and diacritics before indexing.

For more information, see Index options for text and ASCII types.

See Create an index and specify Unicode normalization for an example.

Default: false

caseSensitive

boolean

Optional. Whether the index is case sensitive.

For more information, see Index options for text and ASCII types.

See Create an index and specify case sensitivity for an example.

Default: true

ifNotExists

boolean

Optional. Whether the command should silently succeed even if an index with the given name already exists in the keyspace and no new index was created.

This option only checks index names. It does not check index definitions.

Default: false

timeout

number | TimeoutDescriptor

A timeout, in milliseconds, to impose on the underlying API request.

Use the createIndex method, which belongs to the com.datastax.astra.client.tables.Table class.

Method signature
void createIndex(
  String indexName,
  String columnName
)
void createIndex(
  String indexName,
  String columnName,
  CreateIndexOptions indexOptions
)
void createIndex(
  String indexName,
  TableIndexDefinition indexDefinition,
  CreateIndexOptions indexOptions
)
Name Type Summary

name

str

The name of the index.

Index names for tables must follow these rules:

  • Must be unique within the keyspace

  • Can contain letters, numbers, and underscores

  • Must have a length of 1 to 100 characters

definition

TableIndexDefinition

The index definition. See Methods of the TableIndexDefinition constructor for more details.

options

CreateIndexOptions

The options for this operation. See Methods of the CreateIndexOptions constructor for more details.

Methods of the TableIndexDefinition constructor
Method Type Summary

column()

string

The name of the table column on which to create the index.

The column name must use snake case, not camel case.

For map columns, you can index the entries, only the keys, or only the values. See Create an index for a map column for an example.

To create vector indexes based on vector columns, see Create a vector index.

options()

TableIndexDefinitionOptions

Methods of the CreateIndexOptions constructor
Method Type Summary

ifNotExists()

boolean

Optional. Whether the command should silently succeed even if an index with the given name already exists in the keyspace and no new index was created.

This option only checks index names. It does not check index definitions.

Default: false

Use the createIndex command.

Command signature
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "createIndex": {
    "name": "INDEX_NAME",
    "definition": {
      "column": "COLUMN_NAME",
      "options": {
        "ascii": BOOLEAN,
        "normalize": BOOLEAN,
        "caseSensitive": BOOLEAN
      }
    }
  }
}'
Name Type Summary

name

string

The name of the index.

Index names for tables must follow these rules:

  • Must be unique within the keyspace

  • Can contain letters, numbers, and underscores

  • Must have a length of 1 to 100 characters

definition.column

string

The name of the table column on which to create the index.

The column name must use snake case, not camel case.

For map columns, you can index the entries, only the keys, or only the values. See Create an index for a map column for an example.

To create vector indexes based on vector columns, see Create a vector index.

definition.options.ascii

boolean

Optional. Whether to convert non-ASCII characters to their US-ASCII equivalent before indexing.

For more information, see Index options for text and ASCII types.

See Create an index and specify ASCII conversion before indexing for an example.

Default: false

definition.options.normalize

boolean

Optional. Whether to normalize Unicode characters and diacritics before indexing.

For more information, see Index options for text and ASCII types.

See Create an index and specify Unicode normalization for an example.

Default: false

definition.options.caseSensitive

boolean

Optional. Whether the index is case sensitive.

For more information, see Index options for text and ASCII types.

See Create an index and specify case sensitivity for an example.

Default: true

Examples

The following examples demonstrate how to create an index.

Create an index

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Index a column
table.create_index("example_index_name", column="example_column")
import { DataAPIClient } from "@datastax/astra-db-ts";

// Get an existing table
const client = new DataAPIClient("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

// Index a column
(async function () {
  await table.createIndex("example_index_name", "example_column");
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("API_ENDPOINT")
            .getTable("TABLE_NAME");

    // Index a column
    table.createIndex("example_index_name", "example_column");
  }
}
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createIndex": {
    "name": "example_index_name",
    "definition": {
      "column": "example_column"
    }
  }
}'

Create an index and specify ASCII conversion before indexing

When you index a text or ASCII column, you can specify whether to convert non-ASCII characters to their US-ASCII equivalent before indexing.

Converting non-ASCII characters can improve search performance by limiting the range of allowed ASCII characters. This option is best for ASCII-only data or ASCII-only applications where you can safely ignore non-ASCII characters. It is not recommended for multilingual data or applications that must support non-ASCII characters.

For more information, see Index options for text and ASCII types.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient
from astrapy.info import TableIndexOptions

# Get an existing table
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Index a column
table.create_index(
    "example_index_name",
    column="example_column",
    options=TableIndexOptions(
        ascii=True,
    ),
)
import { DataAPIClient } from "@datastax/astra-db-ts";

// Get an existing table
const client = new DataAPIClient("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

// Index a column
(async function () {
  await table.createIndex("example_index_name", "example_column", {
    options: {
      ascii: true,
    },
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.CreateIndexOptions;
import com.datastax.astra.client.tables.definition.indexes.TableIndexDefinitionOptions;
import com.datastax.astra.client.tables.definition.indexes.TableRegularIndexDefinition;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("API_ENDPOINT")
            .getTable("TABLE_NAME");

    // Index a column
    TableRegularIndexDefinition definition =
        new TableRegularIndexDefinition()
            .column("example_column")
            .options(new TableIndexDefinitionOptions().ascii(true));

    CreateIndexOptions options = new CreateIndexOptions();
    table.createIndex("example_index_name", definition, options);
  }
}
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createIndex": {
    "name": "example_index_name",
    "definition": {
      "column": "example_column",
      "options": {
        "ascii": true
      }
    }
  }
}'

Create an index and specify Unicode normalization

When you index a text or ASCII column, you can specify whether to normalize Unicode characters and diacritics before indexing.

Normalizing Unicode characters can improve search consistency and inclusivity. This option is best for data sets that can contain multiple Unicode versions of the same character, such as multilingual data or non-standardized user input.

For more information, see Index options for text and ASCII types.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient
from astrapy.info import TableIndexOptions

# Get an existing table
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Index a column
table.create_index(
    "example_index_name",
    column="example_column",
    options=TableIndexOptions(
        normalize=True,
    ),
)
import { DataAPIClient } from "@datastax/astra-db-ts";

// Get an existing table
const client = new DataAPIClient("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

// Index a column
(async function () {
  await table.createIndex("example_index_name", "example_column", {
    options: {
      normalize: true,
    },
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.CreateIndexOptions;
import com.datastax.astra.client.tables.definition.indexes.TableIndexDefinitionOptions;
import com.datastax.astra.client.tables.definition.indexes.TableRegularIndexDefinition;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("API_ENDPOINT")
            .getTable("TABLE_NAME");

    // Index a column
    TableRegularIndexDefinition definition =
        new TableRegularIndexDefinition()
            .column("example_column")
            .options(new TableIndexDefinitionOptions().normalize(true));

    CreateIndexOptions options = new CreateIndexOptions();
    table.createIndex("example_index_name", definition, options);
  }
}
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createIndex": {
    "name": "example_index_name",
    "definition": {
      "column": "example_column",
      "options": {
        "normalize": true
      }
    }
  }
}'

Create an index and specify case sensitivity

When you index a text or ASCII column, you can specify whether the index is case sensitive.

Enforcing case sensitivity is best for data sets where you want to enforce exact matches based on capitalization.

For more information, see Index options for text and ASCII types.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient
from astrapy.info import TableIndexOptions

# Get an existing table
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Index a column
table.create_index(
    "example_index_name",
    column="example_column",
    options=TableIndexOptions(
        case_sensitive=False,
    ),
)
import { DataAPIClient } from "@datastax/astra-db-ts";

// Get an existing table
const client = new DataAPIClient("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

// Index a column
(async function () {
  await table.createIndex("example_index_name", "example_column", {
    options: {
      caseSensitive: false,
    },
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.CreateIndexOptions;
import com.datastax.astra.client.tables.definition.indexes.TableIndexDefinitionOptions;
import com.datastax.astra.client.tables.definition.indexes.TableRegularIndexDefinition;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("API_ENDPOINT")
            .getTable("TABLE_NAME");

    // Index a column
    TableRegularIndexDefinition definition =
        new TableRegularIndexDefinition()
            .column("example_column")
            .options(new TableIndexDefinitionOptions().caseSensitive(true));

    CreateIndexOptions options = new CreateIndexOptions();
    table.createIndex("example_index_name", definition, options);
  }
}
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createIndex": {
    "name": "example_index_name",
    "definition": {
      "column": "example_column",
      "options": {
        "caseSensitive": false
      }
    }
  }
}'

Create an index for a map column

For map columns, you can index the entries, only the keys, or only the values.

To index the entries, specify the column name as demonstrated in the "Create an index" example.

To index only the keys, specify the column name along with $keys:

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Index a the keys of a map column
table.create_index(name="example_index_name", column={"example_map_column": "$keys"})
import { DataAPIClient } from "@datastax/astra-db-ts";

// Get an existing table
const client = new DataAPIClient("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

// Index a column
(async function () {
  await table.createIndex("example_index_name", {
    example_map_column: "$keys",
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.indexes.TableIndexMapTypes;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("API_ENDPOINT")
            .getTable("TABLE_NAME");

    // Index a column
    table.createIndex("example_index_name", "example_map_column", TableIndexMapTypes.KEYS);
  }
}
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createIndex": {
    "name": "example_index_name",
    "definition": {
      "column": {"example_map_column": "$keys"}
    }
  }
}'

To index only the values, specify the column name along with $values:

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Index a the keys of a map column
table.create_index(name="example_index_name", column={"example_map_column": "$values"})
import { DataAPIClient } from "@datastax/astra-db-ts";

// Get an existing table
const client = new DataAPIClient("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

// Index a column
(async function () {
  await table.createIndex("example_index_name", {
    example_map_column: "$values",
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.indexes.TableIndexMapTypes;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("API_ENDPOINT")
            .getTable("TABLE_NAME");

    // Index a column
    table.createIndex("example_index_name", "example_map_column", TableIndexMapTypes.VALUES);
  }
}
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createIndex": {
    "name": "example_index_name",
    "definition": {
      "column": {"example_map_column": "$values"}
    }
  }
}'

Create an index only if the index does not exist

Use this option to silently do nothing if an index with the specified name already exists.

This option only checks index names. It doesn’t check the type or content of any existing indexes.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Index a column
table.create_index(
    "example_index_name",
    column="example_column",
    if_not_exists=True,
)
import { DataAPIClient } from "@datastax/astra-db-ts";

// Get an existing table
const client = new DataAPIClient("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

// Index a column
(async function () {
  await table.createIndex("example_index_name", "example_column", {
    ifNotExists: false,
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.CreateIndexOptions;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("API_ENDPOINT")
            .getTable("TABLE_NAME");

    // Index a column
    CreateIndexOptions options = new CreateIndexOptions().ifNotExists(true);
    table.createIndex("example_index_name", "example_column", options);
  }
}

This option has no literal equivalent in HTTP. Instead, you can list the index names to see if an index with the name already exists.

Client reference

  • Python

  • TypeScript

  • Java

  • curl

For more information, see the client reference.

For more information, see the client reference.

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax, an IBM Company | Privacy policy | Terms of use | Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com