Index Lifecycle Management

15/10/2026

GraphRAG 1.3.0

Vector database indexes require strict schema definitions. Given that these indexes depend on precise mathematical dimensions, their field parameters cannot be modified dynamically after initialization.

This section covers:

index creation
reindexing when changing models
deleting an index safely

Schemas must be defined explicitly before ingestion. When the database engine relies on dynamic mapping inference, it interprets floating-point arrays as standard numeric arrays rather than initializing a spatial index structure (k-NN/HNSW). This effectively disables vector similarity search capabilities.

The following payloads define an index named my_vector_index optimized for a 1024-dimensional embedding structure, compatible with models such as amazon.titan-embed-text-v2:0 or cohere.embed-english-v3.

To maintain consistency across workflows, all three target configurations adhere to the same data contract for both ingestion and retrieval:

id (keyword):
Stored as an untokenized structured string, enabling precise document retrieval without text analysis.
title (text with a .keyword multi-field):
Full-text search capability is enabled on the title string using the standard analyzer, while an indexed sub-field (title.keyword) is retained for exact sorting, grouping, or strict matching operations.
content (text):
Stores the unstructured text snippet passed to the embedding model. The Components service reads this field path to return text payloads to workflow automation orchestrators.
source (keyword):
A high-performance metadata filter path used to isolate document origins (for example, filtering strictly for source: "Confluence" or source: "Jira" during a vector query).
vector_embedding (dense_vector / knn_vector):
A dense floating-point array containing exactly 1024 dimensions. This field uses cosine similarity metrics to evaluate how conceptually close documents are to incoming search queries.

The following examples illustrate the expected structure:

curl -X PUT "http://localhost:9200/my_vector_index" \
     -H "Content-Type: application/json" \
     -d '{
  "settings": {
    "index": {
      "number_of_shards": 1,
      "number_of_replicas": 0
    }
  },
  "mappings": {
    "properties": {
      "id": {
        "type": "keyword"
      },
      "title": {
        "type": "text",
        "fields": {
          "keyword": {
            "type": "keyword",
            "ignore_above": 256
          }
        }
      },
      "content": {
        "type": "text",
        "analyzer": "standard"
      },
      "source": {
        "type": "keyword"
      },
      "vector_embedding": {
        "type": "dense_vector",
        "dims": 1024,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "int8_hnsw"
        }
      }
    }
  }
}'

curl -X PUT "http://localhost:9200/my_vector_index" \
     -H "Content-Type: application/json" \
     -d '{
  "settings": {
    "index": {
      "knn": true,
      "number_of_shards": 1,
      "number_of_replicas": 0
    }
  },
  "mappings": {
    "properties": {
      "id": {
        "type": "keyword"
      },
      "title": {
        "type": "text",
        "fields": {
          "keyword": {
            "type": "keyword",
            "ignore_above": 256
          }
        }
      },
      "content": {
        "type": "text",
        "analyzer": "standard"
      },
      "source": {
        "type": "keyword"
      },
      "vector_embedding": {
        "type": "knn_vector",
        "dimension": 1024,
        "method": {
          "name": "hnsw",
          "space_type": "cosinesimil",
          "engine": "faiss"
        }
      }
    }
  }
}'

Serverless architecture constraints

No payload settings:
Amazon OpenSearch Serverless does not accept a top-level "settings" block (such as index.knn), nor does it accept explicit algorithm tuning parameters (such as engine or method) inside the property field. The serverless engine configures and optimizes HNSW indexing automatically.
Authentication enforced:
Serverless collections do not support unauthenticated HTTP or Basic Authentication. Your HTTP client must sign all requests using AWS Signature Version 4 (SigV4).

curl -X PUT "https://<your-collection-endpoint>.us-east-1.aoss.amazonaws.com/my_vector_index" \
     -H "Content-Type: application/json" \
     -d '{
  "mappings": {
    "properties": {
      "id": {
        "type": "keyword"
      },
      "title": {
        "type": "text",
        "fields": {
          "keyword": {
            "type": "keyword",
            "ignore_above": 256
          }
        }
      },
      "content": {
        "type": "text",
        "analyzer": "standard"
      },
      "source": {
        "type": "keyword"
      },
      "vector_embedding": {
        "type": "knn_vector",
        "dimension": 1024
      }
    }
  }
}'

When migrating to a different embedding provider or model (for example, upgrading from Cohere's embed-english-v3 at 1024 dimensions to OpenAI's text- embedding-3-large at 3072 dimensions), indices cannot be updated in place. Attempting to insert a 3072-dimensional vector into an index configured for 1024 dimensions will produce an immediate schema mismatch validation error.

Because the vector store cannot automatically recalculate text into new vector representations, all source documents must be re-embedded.

Step 1: Create the New Target Index

Initialize a new target index (for example, my_vector_index_v2) using the updated mapping schema and the new dimension size (for example, 3072 dimensions).

curl -X PUT "http://localhost:9200/my_vector_index_v2" \
     -H "Content-Type: application/json" \
     -d '{
  "mappings": {
    "properties": {
      "id": { "type": "keyword" },
      "title": { "type": "text" },
      "content": { "type": "text" },
      "source": { "type": "keyword" },
      "vector_embedding": {
        "type": "dense_vector",
        "dims": 3072,
        "index": true,
        "similarity": "cosine"
      }
    }
  }
}'

Step 2: Route New Data via GraphRAG Workflows or Ingestion Pipelines
Before modifying your historical data, update your ingestion pipelines to point to the new index and use the new model configuration. All incoming documents will now be automatically vectorized at 3072 dimensions and stored in my_vector_index_v2.
Step 3: Backfill Historical Documents
To migrate your existing documents, extract them from the old index (or from another primary source) and re-submit them for embedding. You can do this by directly using the embedding provider of your choice or by calling the Component Service /embed endpoint.
Step 4: Switch Search Workflows to the New Index
Once the backfill is complete and my_vector_index_v2 contains your entire document library, update the environment variables or configuration presets that reference the vector index. Alternatively, you can use an alias to retain the original index name while pointing to the new index.

Warning

Executing a DELETE request permanently removes the targeted index destroying both the stored data and the underlying schema mappings. A curl command to delete the index may look like this curl -X DELETE "http://localhost:9200/my_vector_index";.

Because the Components service does not manage the index lifecycle, any active workflows or pipelines that attempt to query or write to a deleted index will fail immediately.

To restore functionality after deletion, administrators must explicitly recreate the schema mappings using the payloads defined in the Index Creation section above before repopulating or searching the index.

In this section: