> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcollate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Search Index

> Create a new search index entity with fields, mappings, owners, tags, and configuration within a search service using the Collate REST API for search infrastructure.

# Create a Search Index

Create a new search index within a search service.

## Body Parameters

**name** `string` *required*

Name of the search index. Must be unique within the parent search service.

**service** `string` *required*

Fully qualified name of the parent SearchService, for example `elasticsearch_sample`.

**fields** `array`

Array of field objects defining the index schema.

**properties**

**name** `string`

Name of the field.

**dataType** `string`

Data type of the field, for example `TEXT`, `KEYWORD`, `INT`, `OBJECT`.

**description** `string`

Description of the field.

**children** `array`

Nested child fields for complex types.

**displayName** `string`

Human-readable display name for the search index.

**description** `string`

Description of the search index in Markdown format.

**owners** `array`

Array of owner references (users or teams) to assign to the search index.

**properties**

**id** `string`

UUID of the owner entity.

**type** `string`

Type of owner entity, for example `user`, `team`.

**name** `string`

Name of the owner entity.

**domains** `array`

Fully qualified names of the domains to assign for governance purposes.

**tags** `array`

Array of classification tags to apply to the search index.

**properties**

**tagFQN** `string` *required*

Fully qualified name of the tag.

**labelType** `string`

Type of label, for example `Manual`, `Derived`, `Propagated`.

**state** `string`

State of the tag, for example `Suggested`, `Confirmed`.

**extension** `object`

Custom property values defined by your organization's metadata schema.

```python POST /v1/searchIndexes theme={null}
from metadata.sdk import configure
from metadata.sdk.entities import SearchIndexes
from metadata.generated.schema.api.data.createSearchIndex import CreateSearchIndexRequest

configure(
    host="https://your-company.getcollate.io/api",
    jwt_token="your-jwt-token"
)

request = CreateSearchIndexRequest(
    name="table_search_index",
    displayName="TableSearchIndex",
    service="elasticsearch_sample",
    description="Search index for table entities",
    fields=[
        {"name": "name", "dataType": "TEXT"},
        {"name": "description", "dataType": "TEXT"}
    ]
)

search_index = SearchIndexes.create(request)
print(f"Created: {search_index.fullyQualifiedName.root}")
```

```java POST /v1/searchIndexes theme={null}
import java.util.List;
import org.openmetadata.schema.api.data.CreateSearchIndex;
import org.openmetadata.schema.entity.data.SearchIndex;
import org.openmetadata.schema.type.SearchIndexDataType;
import org.openmetadata.schema.type.SearchIndexField;
import org.openmetadata.sdk.fluent.SearchIndexes;

// client is an initialized OpenMetadataClient.
SearchIndexes.setDefaultClient(client);

CreateSearchIndex request = new CreateSearchIndex()
    .withName("table_search_index")
    .withDisplayName("TableSearchIndex")
    .withService("elasticsearch_sample")
    .withDescription("Search index for table entities")
    .withFields(List.of(
        new SearchIndexField().withName("name").withDataType(SearchIndexDataType.TEXT),
        new SearchIndexField().withName("description").withDataType(SearchIndexDataType.TEXT)));

SearchIndex searchIndex = SearchIndexes.create(request);
```

```bash POST /v1/searchIndexes theme={null}
curl -X POST "{base_url}/api/v1/searchIndexes" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "table_search_index",
    "displayName": "TableSearchIndex",
    "service": "elasticsearch_sample",
    "description": "Search index for table entities",
    "fields": [
      {"name": "name", "dataType": "TEXT"},
      {"name": "description", "dataType": "TEXT"}
    ]
  }'
```

```json Response theme={null}
{
  "id": "f5b0fa81-f241-4508-9219-dae31dcced18",
  "name": "table_search_index",
  "fullyQualifiedName": "elasticsearch_sample.table_search_index",
  "displayName": "TableSearchIndex",
  "version": 0.1,
  "updatedAt": 1769982670810,
  "updatedBy": "admin",
  "service": {
    "id": "search-service-id",
    "type": "searchService",
    "name": "elasticsearch_sample",
    "fullyQualifiedName": "elasticsearch_sample",
    "deleted": false
  },
  "serviceType": "ElasticSearch",
  "fields": [
    {"name": "name", "dataType": "TEXT"},
    {"name": "description", "dataType": "TEXT"}
  ],
  "deleted": false,
  "owners": [],
  "tags": [],
  "followers": [],
  "votes": {
    "upVotes": 0,
    "downVotes": 0
  },
  "domains": []
}
```

***

## Returns

Returns the created search index object with all specified properties and system-generated fields.

## Response

**id** `string`

Unique identifier for the search index (UUID format).

**name** `string`

Search index name.

**fullyQualifiedName** `string`

Fully qualified name in format `service.indexName`.

**displayName** `string`

Human-readable display name.

**description** `string`

Description of the search index in Markdown format.

**service** `object`

Reference to the parent search service.

**properties**

**id** `string`

UUID of the search service.

**type** `string`

Type of entity (always `searchService`).

**name** `string`

Name of the search service.

**fullyQualifiedName** `string`

Fully qualified name of the search service.

**fields** `array`

Array of field definitions for the index schema.

**properties**

**name** `string`

Name of the field.

**dataType** `string`

Data type of the field.

**description** `string`

Description of the field.

**children** `array`

Nested child fields.

**serviceType** `string`

Type of search service, for example ElasticSearch, OpenSearch.

**owners** `array`

List of owners assigned to the search index.

**properties**

**id** `string`

UUID of the owner entity.

**type** `string`

Type of owner entity, for example `user`, `team`.

**name** `string`

Name of the owner entity.

**domains** `array`

Domain assignments for governance.

**tags** `array`

Classification tags applied to the search index.

**properties**

**tagFQN** `string`

Fully qualified name of the tag.

**labelType** `string`

Type of label, for example `Manual`, `Derived`, `Propagated`.

**state** `string`

State of the tag, for example `Suggested`, `Confirmed`.

**extension** `object`

Custom property values defined by your organization's metadata schema.

**version** `number`

Version number for the entity (starts at 0.1).

***

## Create or Update (PUT)

Use `PUT /v1/searchIndexes` instead of `POST` to perform an upsert. If a search index with the same `fullyQualifiedName` already exists, it will be updated; otherwise, a new search index is created. The request body is the same as `POST`.

```bash theme={null}
curl -X PUT "{base_url}/api/v1/searchIndexes" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ ... same body as POST ... }'
```

> [!NOTE]
>
> `PUT` will not return a `409` conflict error if the entity already exists -- it will update the existing entity instead. However, for certain fields (such as description, tags, owners, and custom properties), `PUT` preserves an already-populated value instead of overwriting it with an empty or omitted one -- the exact behavior depends on the field and the calling user or bot's permissions, not a blanket rule. See [Entity Update Behavior](https://docs.getcollate.io/api-reference/entity-updates.md) for the full preserve/merge rules. Use `PATCH` to intentionally replace an existing value.

***

## Bulk Create or Update (PUT)

Use `PUT /v1/searchIndexes/bulk` to create or update multiple search indexes in a single request. The request body is an array of create request objects.

```bash theme={null}
curl -X PUT "{base_url}/api/v1/searchIndexes/bulk" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '[
    { "name": "index_one", "service": "elasticsearch_sample" },
    { "name": "index_two", "service": "elasticsearch_sample" }
  ]'
```

***

## Error Handling

| Code | Error Type | Description |
| - | - | - |
| `400` | `BAD_REQUEST` | Invalid request body or missing required fields |
| `401` | `UNAUTHORIZED` | Invalid or missing authentication token |
| `403` | `FORBIDDEN` | User lacks permission to create search indexes |
| `409` | `ENTITY_ALREADY_EXISTS` | Search index with same name already exists in service (POST only) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.