Create an index

This Astra DB Serverless feature is currently in public preview. Development is ongoing, and the features and functionality are subject to change. Astra DB Serverless, and the use of such, is subject to the DataStax Preview Terms.

The Data API tables commands are available through HTTP and the clients.

If you use a client, tables commands are available only in client versions 2.0-preview or later. For more information, see Data API client upgrade guide.

Creates a new index for a column in a table in a Serverless (Vector) 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 manage indexes, your application token must have the same level of permissions that you need to manage tables.

Method signature

Python
TypeScript
Java
curl

The following method belongs to the astrapy.Table class.

create_index(
  name: str,
  *,
  column: str,
  options: TableIndexOptions | dict[str, Any],
  if_not_exists: bool,
  table_admin_timeout_ms: int,
  request_timeout_ms: int,
  timeout_ms: int,
) -> None

The following method belongs to the Table class.

async createIndex(
  name: string,
  column: WSchema | string,
  options?: {
    ifNotExists?: boolean,
    options?: {
      ascii?: boolean,
      normalize?: boolean,
      caseSensitive?: boolean,
      timeout?: number | TimeoutDescriptor,
    },
  },
): void

The following methods belong to the com.datastax.astra.client.tables.Table class.

void createIndex(
  String indexName,
  String columnName
)

void createIndex(
  String indexName,
  String columnName,
  CreateIndexOptions indexOptions
)

void createIndex(
  String indexName,
  TableIndexDefinition indexDefinition,
  CreateIndexOptions indexOptions
)

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "createIndex": {
    "name": "INDEX_NAME",
    "definition": {
      "column": "COLUMN_NAME",
      "options": {
        "ascii": BOOLEAN,
        "normalize": BOOLEAN,
        "caseSensitive": BOOLEAN
      }
    }
  }
}'

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

Name Type Summary

name

str

The name of the index.

Index names must be unique within a keyspace.

column

str

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

You cannot create indexes based on map, list, or set columns. To create vector indexes based on vector columns, see Create a vector index.

options

TableIndexOptions | dict | None

Specifies Index options for text and ascii types. If passed, it must be an instance of TableIndexOptions or an equivalent dictionary.

if_not_exists

bool | None

If True, and an index with the given name already exists in the keyspace, then the command succeeds and silently does nothing. In this case, no actual index creation takes place on the database.

If False (default), an error occurs if an index with the specified name already exists.

if_not_exists: True, does not check the type or content of any existing indexes. This parameter checks index names only.

This means that the command succeeds if the given index name is already in use, even if the type or indexed column is different.

table_admin_timeout_ms

int | None

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.

Name Type Summary

Name	Type	Summary
`name`	`string`	The name of the index. Index names must be unique within a keyspace.
`column`	`string`	The name of the table column on which to create the index. You cannot create indexes based on `map`, `list`, or `set` columns. To create vector indexes based on `vector` columns, see Create a vector index. An error occurs if the given column is already indexed or isn’t an indexable type.
`options?`	`TableCreateIndexOptions`	The options for this operation.

name

string

The name of the index.

Index names must be unique within a keyspace.

column

string

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

You cannot create indexes based on map, list, or set columns. To create vector indexes based on vector columns, see Create a vector index.

An error occurs if the given column is already indexed or isn’t an indexable type.

options?

TableCreateIndexOptions

The options for this operation.

Options (TableCreateIndexOptions):

Name Type Summary

ifNotExists?

boolean

If true, and an index with the given name already exists in the keyspace, then the command succeeds and silently does nothing. In this case, no actual index creation takes place on the database.

If false (default), an error occurs if an index with the specified name already exists.

ifNotExists: true, does not check the type or content of any existing indexes. This parameter checks index names only.

This means that the command succeeds if the given index name is already in use, even if the type or indexed column is different.

options.ascii?

boolean

Whether to convert non-ASCII characters to their US-ASCII equivalent before indexing. The default is false. See Index options for text and ascii types.

options.normalize?

boolean

Whether to normalize Unicode characters and diacritics before indexing. The default is false. See Index options for text and ascii types.

options.caseSensitive?

boolean

Whether the index is case sensitive. The default is true. See Index options for text and ascii types.

timeout?

number | TimeoutDescriptor

The client-side timeout for this operation.

Name Type Summary

name

str

The name of the index.

Index names must be unique within a keyspace.

definition

TableIndexDefinition

Definition of the index to create. Requires the name of the column to index. For text and ascii columns, you can specify index options.

You cannot create indexes based on map, list, or set columns. To create vector indexes based on vector columns, see Create a vector index.

options

CreateIndexOptions

A specialization of index creation options, including ifNotExists and timeout.

If ifNotExists(true), and an index with the given name already exists in the keyspace, then the command succeeds and silently does nothing. In this case, no actual index creation takes place on the database.

If ifNotExists(false) (default), an error occurs if an index with the specified name already exists.

ifNotExists(true), does not check the type or content of any existing indexes. This parameter checks index names only.

This means that the command succeeds if the given index name is already in use, even if the type or indexed column is different.

Name Type Summary

Name	Type	Summary
`createIndex`	`command`	The Data API command to create an index for a table in a Serverless (Vector) database. It acts as a container for all the attributes and settings required to create the index.
`name`	`string`	The name of the index. Index names must be unique within a keyspace.
`definition`	`object`	Contains the `column` and `options` for the index.
`definition.column`	`string`	The name of the table column on which to create the index. You cannot create indexes based on `map`, `list`, or `set` columns. To create vector indexes based on `vector` columns, see Create a vector index.
`definition.options.ascii`	`boolean`	Whether to convert non-ASCII characters to their US-ASCII equivalent before indexing. The default is false. See Index options for text and ascii types.
`definition.options.normalize`	`boolean`	Whether to normalize Unicode characters and diacritics before indexing. The default is false. See Index options for text and ascii types.
`definition.options.caseSensitive`	`boolean`	Whether the index is case sensitive. The default is true. See Index options for text and ascii types.

createIndex

command

The Data API command to create an index for a table in a Serverless (Vector) database. It acts as a container for all the attributes and settings required to create the index.

name

string

The name of the index.

Index names must be unique within a keyspace.

definition

object

Contains the column and options for the index.

definition.column

string

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

You cannot create indexes based on map, list, or set columns. To create vector indexes based on vector columns, see Create a vector index.

definition.options.ascii

boolean

Whether to convert non-ASCII characters to their US-ASCII equivalent before indexing. The default is false. See Index options for text and ascii types.

definition.options.normalize

boolean

Whether to normalize Unicode characters and diacritics before indexing. The default is false. See Index options for text and ascii types.

definition.options.caseSensitive

boolean

Whether the index is case sensitive. The default is true. See Index options for text and ascii types.

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("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');

// Index a column
(async function () {
  await table.createIndex(
    "example_index_name",
    "example_column",
  );
})();

package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.rows.Row;

public class CreateIndex {

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

        // Index a column
        table.createIndex("example_index_name", "example_column");
    }
}

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_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("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_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,
      },
    }
  );
})();

package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.tables.commands.options.CreateIndexOptions;
import com.datastax.astra.client.tables.definition.indexes.TableIndexDefinition;

public class CreateIndex {

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

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

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_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("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_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,
      },
    }
  );
})();

package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.tables.commands.options.CreateIndexOptions;
import com.datastax.astra.client.tables.definition.indexes.TableIndexDefinition;

public class CreateIndex {

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

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

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_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("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_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,
      },
    }
  );
})();

package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.tables.commands.options.CreateIndexOptions;
import com.datastax.astra.client.tables.definition.indexes.TableIndexDefinition;

public class CreateIndex {

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

        // Index a column
        TableIndexDefinition definition = new TableIndexDefinition()
          .column("example_column")
          .caseSensitive(false);
        CreateIndexOptions options = new CreateIndexOptions();
        table.createIndex("example_index_name", definition, options);
    }
}

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "createIndex": {
    "name": example_index_name",
    "definition": {
      "column": "example_column",
      "options": {
        "caseSensitive": false
      }
    }
  }
}'

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("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');

// Index a column
(async function () {
  await table.createIndex(
    "example_index_name",
    "example_column",
    options: {
      ifNotExists: true,
    },
  );
})();

package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.tables.commands.options.CreateIndexOptions;

public class CreateIndex {

    public static void main(String[] args) {
        // Get an existing table
        Table<Row> table = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_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.

Client reference documentation is not applicable for HTTP.

Create an index

Method signature

Result

Parameters

Examples

Create an index

Create an index and specify ASCII conversion before indexing

Create an index and specify Unicode normalization

Create an index and specify case sensitivity

Create an index only if the index does not exist

Client reference

Was this helpful?

Give Feedback