Enable Semantic Search

Prerequisites

OpenSearch or Elasticsearch as your search backend
An external embedding provider: OpenAI, AWS Bedrock, Google, or DJL for HuggingFace models.
Network access from the OpenMetadata server to the embedding provider API (unless using DJL)

Overview

Semantic Search enhances OpenMetadata’s search capabilities by using vector embeddings to understand the meaning behind queries, rather than relying solely on keyword matching. This means users and AI agents can search using natural language — for example, “tables with customer demographics and purchase history” — and get meaningful results even if those exact words don’t appear in the metadata.

Semantic Search supports both OpenSearch and Elasticsearch as the search backend. The OpenSearch-specific hybrid search pipeline (which blends keyword and semantic scores server-side) is not available on Elasticsearch. Core vector/KNN search works the same on both backends.

Semantic Search also powers the Semantic Search MCP tool, enabling AI assistants connected via the Model Context Protocol to perform natural language queries against your metadata catalog.

How It Works

Text Construction

For each entity, a structured text representation is constructed from its metadata — including name, description, entity type, tags, glossary terms, owners, and other relevant fields.

Embedding Generation & Vector Indexing

The text is sent to the configured embedding provider to generate a numerical vector (embedding), which is stored in a dedicated dataAssetEmbeddings index (<clusterAlias>_dataAssetEmbeddings if you’ve set a cluster alias) using the HNSW algorithm with cosine similarity. At query time, the search text is also embedded and a KNN (K-Nearest Neighbor) similarity search finds the most relevant results.

Automatic Lifecycle Management

Embeddings follow the same lifecycle as the entities themselves. When entities are created, updated, deleted, or restored, their embeddings are automatically kept in sync using the same indexing strategies the platform already uses for search. No manual intervention is required after initial setup.

Supported Entity Types

table, glossary, glossaryTerm, chart, dashboard, dashboardDataModel, database, databaseSchema, dataProduct, pipeline, mlmodel, metric, apiEndpoint, apiCollection, page, storedProcedure, searchIndex, topic, contextMemory, container, testSuite, testCase, llmModel, aiApplication, promptTemplate, mcpServer, aiGovernancePolicy, aiGovernanceFramework

Configuration

Semantic Search settings are split across two sections of openmetadata.yaml. The master switch stays under elasticsearch.naturalLanguageSearch, while the embedding provider, model, and credentials live under llmConfiguration — the same section used for platform-wide LLM completions. All settings can be overridden with environment variables.

LLM_ENABLED and LLM_PROVIDER configure the platform’s chat completion client. They do not enable or select Semantic Search’s vector embeddings — that’s controlled by SEMANTIC_SEARCH_ENABLED and llmConfiguration.embeddings.provider instead.

Enable Semantic Search

Environment Variable	Default	Description
`SEMANTIC_SEARCH_ENABLED`	`false`	Master switch to enable semantic search
`EMBEDDING_PROVIDER`	`bedrock`	Embedding provider to use: `openai`, `bedrock`, `google`, or `djl`
`MAX_CONCURRENT_EMBEDDING_REQUESTS`	`10`	Maximum number of concurrent calls to the embedding provider

elasticsearch:
  naturalLanguageSearch:
    semanticSearchEnabled: ${SEMANTIC_SEARCH_ENABLED:-false}

llmConfiguration:
  embeddings:
    provider: ${EMBEDDING_PROVIDER:-bedrock}
    maxConcurrentRequests: ${MAX_CONCURRENT_EMBEDDING_REQUESTS:-10}

Embedding Providers

Choose one of the following embedding providers and configure it accordingly.

OpenAI
AWS Bedrock
Google
DJL

Supports both OpenAI and Azure OpenAI endpoints. Credentials live under llmConfiguration.openai, shared with the platform’s chat completion config; the embedding model and dimension live under llmConfiguration.embeddings.openai.

Environment Variable	Default	Description
`LLM_OPENAI_API_KEY`	`""`	Your OpenAI API key
`LLM_OPENAI_ENDPOINT`	`""`	API endpoint. For Azure, use `https://your-resource.openai.azure.com`
`LLM_OPENAI_DEPLOYMENT`	`""`	Deployment name (required for Azure OpenAI)
`LLM_OPENAI_API_VERSION`	`2024-02-01`	API version (Azure OpenAI)
`OPENAI_EMBEDDING_MODEL_ID`	`text-embedding-3-small`	Embedding model to use
`OPENAI_EMBEDDING_DIMENSION`	`1536`	Embedding vector dimension

elasticsearch:
  naturalLanguageSearch:
    semanticSearchEnabled: true

llmConfiguration:
  openai:
    apiKey: ${LLM_OPENAI_API_KEY:-""}
    endpoint: ${LLM_OPENAI_ENDPOINT:-""}
    deploymentName: ${LLM_OPENAI_DEPLOYMENT:-""}
    apiVersion: ${LLM_OPENAI_API_VERSION:-"2024-02-01"}
  embeddings:
    provider: openai
    openai:
      embeddingModelId: ${OPENAI_EMBEDDING_MODEL_ID:-"text-embedding-3-small"}
      embeddingDimension: ${OPENAI_EMBEDDING_DIMENSION:-1536}

Uses AWS Bedrock for embedding generation. AWS credentials live under llmConfiguration.bedrock.awsConfig, shared with the platform’s chat completion config; the embedding model and dimension live under llmConfiguration.embeddings.bedrock.Static credentials always take priority: if AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are both set, OpenMetadata uses them regardless of BEDROCK_AWS_IAM_AUTH_ENABLED. To actually authenticate with the server’s IAM role, leave both of those empty.

Environment Variable	Default	Description
`BEDROCK_AWS_IAM_AUTH_ENABLED`	`true`	Use the server’s IAM role instead of static credentials. Only takes effect when `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` are both empty — a static key pair always overrides it
`AWS_DEFAULT_REGION`	`""`	AWS region
`AWS_ACCESS_KEY_ID`	`""`	AWS access key. Must be left empty for IAM auth to be used
`AWS_SECRET_ACCESS_KEY`	`""`	AWS secret access key. Must be left empty for IAM auth to be used
`AWS_SESSION_TOKEN`	`""`	AWS session token (only used alongside static access key/secret)
`AWS_BEDROCK_EMBED_MODEL_ID`	`amazon.titan-embed-text-v2:0`	Bedrock embedding model ID
`AWS_BEDROCK_EMBEDDING_DIMENSION`	`512`	Embedding vector dimension

elasticsearch:
  naturalLanguageSearch:
    semanticSearchEnabled: true

llmConfiguration:
  bedrock:
    awsConfig:
      enabled: ${BEDROCK_AWS_IAM_AUTH_ENABLED:-true}
      region: ${AWS_DEFAULT_REGION:-""}
      accessKeyId: ${AWS_ACCESS_KEY_ID:-""}
      secretAccessKey: ${AWS_SECRET_ACCESS_KEY:-""}
      sessionToken: ${AWS_SESSION_TOKEN:-""}
  embeddings:
    provider: bedrock
    bedrock:
      embeddingModelId: ${AWS_BEDROCK_EMBED_MODEL_ID:-"amazon.titan-embed-text-v2:0"}
      embeddingDimension: ${AWS_BEDROCK_EMBEDDING_DIMENSION:-512}

Uses Google’s Gemini embedding models. Credentials live under llmConfiguration.google, shared with the platform’s chat completion config; the embedding model and dimension live under llmConfiguration.embeddings.google.

Environment Variable	Default	Description
`LLM_GOOGLE_API_KEY`	`""`	Your Google API key
`GOOGLE_EMBEDDING_MODEL_ID`	`gemini-embedding-001`	Embedding model to use
`GOOGLE_EMBEDDING_DIMENSION`	`768`	Embedding vector dimension

elasticsearch:
  naturalLanguageSearch:
    semanticSearchEnabled: true

llmConfiguration:
  google:
    apiKey: ${LLM_GOOGLE_API_KEY:-""}
  embeddings:
    provider: google
    google:
      embeddingModelId: ${GOOGLE_EMBEDDING_MODEL_ID:-"gemini-embedding-001"}
      embeddingDimension: ${GOOGLE_EMBEDDING_DIMENSION:-768}

Uses Deep Java Library to run embedding models locally. No external API calls or credentials required.

DJL downloads and runs the HuggingFace model in your server directly. This will have an impact on the necessary resources depending on the chosen model. If you are resource constrainted, use external providers.The example model we provide is a rather small one that fits development/testing use cases. In case of choosing DJL, choose a model that fits your use case.

Environment Variable	Default	Description
`DJL_EMBEDDING_MODEL`	`ai.djl.huggingface.pytorch/sentence-transformers/all-MiniLM-L6-v2`	HuggingFace model identifier

The embedding dimension is auto-detected from the model at startup. The default model all-MiniLM-L6-v2 produces 384-dimensional vectors.

elasticsearch:
  naturalLanguageSearch:
    semanticSearchEnabled: true

llmConfiguration:
  embeddings:
    provider: djl
    djl:
      embeddingModel: ${DJL_EMBEDDING_MODEL:-"ai.djl.huggingface.pytorch/sentence-transformers/all-MiniLM-L6-v2"}

Docker Deployment

To enable Semantic Search in a Docker deployment, set the required environment variables in your docker-compose override or .env file:

environment:
  SEMANTIC_SEARCH_ENABLED: "true"
  EMBEDDING_PROVIDER: "openai"
  LLM_OPENAI_API_KEY: "sk-..."
  OPENAI_EMBEDDING_MODEL_ID: "text-embedding-3-small"
  OPENAI_EMBEDDING_DIMENSION: "1536"

Kubernetes Deployment

For Kubernetes deployments using the OpenMetadata Helm chart, add the environment variables to your values.yaml:

openmetadata:
  config:
    extraEnvs:
      - name: SEMANTIC_SEARCH_ENABLED
        value: "true"
      - name: EMBEDDING_PROVIDER
        value: "openai"
      - name: LLM_OPENAI_API_KEY
        valueFrom:
          secretKeyRef:
            name: openmetadata-secrets
            key: openai-api-key
      - name: OPENAI_EMBEDDING_MODEL_ID
        value: "text-embedding-3-small"
      - name: OPENAI_EMBEDDING_DIMENSION
        value: "1536"

Store sensitive values like API keys in Kubernetes Secrets and reference them with secretKeyRef rather than hardcoding them in values.yaml.

Validating the Configuration

After configuring your embedding provider, you can verify that everything is set up correctly by navigating to Settings > Preferences > Health in the OpenMetadata UI. This page shows the status of the embedding provider connection and will flag any misconfiguration.

The Semantic Search health card only appears once SEMANTIC_SEARCH_ENABLED is set to true. It won’t show up if semantic search is still disabled.

Generating Embeddings

Once Semantic Search is enabled, embeddings are generated and kept in sync automatically as entities are created or updated. To generate embeddings for all existing entities, run a Reindex from the OpenMetadata UI (Settings > Applications > Search Indexing). Every Reindex operation computes embeddings taking a fingerprint into account — if the text representation of an entity has not changed since its last embedding, the embedding is not recomputed. This avoids unnecessary calls to the embedding provider and makes re-indexing efficient even for large catalogs. OpenSearch only: as a faster, dedicated alternative to a full Reindex, use the reembed CLI command. It initializes the vector service and processes entities in batches, applying the same fingerprint check described above — entities whose content hasn’t changed are skipped, and the existing vector index is not dropped or recreated. The speedup over a UI Reindex comes from running as a standalone, multithreaded batch job with configurable batch size and producer/consumer thread counts:

./bin/openmetadata-ops.sh reembed --batch-size 100 --producer-threads 2 --consumer-threads 4

This command is implemented against OpenSearch specifically and doesn’t run on an Elasticsearch backend. On Elasticsearch, use the full Reindex from the UI described above instead.

API Reference

Semantic Search exposes a REST API endpoint for vector queries:

POST `/api/v1/search/vector/query`

Performs a semantic search against the vector index. Request Body:

{
  "query": "customer demographics purchase history",
  "filters": {
    "entityType": ["table"],
    "owners": ["admin"],
    "tags": ["PII.Sensitive"],
    "domains": ["Marketing"],
    "tier": ["Tier.Tier1"],
    "serviceType": ["Postgres"]
  },
  "size": 10,
  "k": 1000,
  "threshold": 0.0
}

Parameter	Type	Default	Description
`query`	string	(required)	Natural language search text
`filters`	map	`{}`	Filter map by entity type, owners, tags, domains, tier, service type, certification, or custom properties
`size`	int	`10`	Number of distinct entities to return (max 100)
`k`	int	`500`	KNN parameter — number of nearest neighbors to consider (max 10,000)
`threshold`	double	`0.0`	Minimum similarity score to include in results

Results are deduplicated by parent entity, so you will receive at most size distinct entities even if an entity has multiple text chunks.

Troubleshooting

Semantic Search returns no results

Verify that SEMANTIC_SEARCH_ENABLED is set to true and the server has been restarted.
Confirm your search backend (OpenSearch or Elasticsearch) is reachable and correctly configured.
Check that the dataAssetEmbeddings index (or <clusterAlias>_dataAssetEmbeddings if you’ve set a cluster alias) exists in your search backend.
Run a Reindex to generate embeddings for existing entities.

Embedding generation fails

Verify network connectivity from the OpenMetadata server to your embedding provider.
Check that API keys and credentials are correct.
Review the OpenMetadata server logs for detailed error messages.

​Enable Semantic Search

​Prerequisites

​Overview

​How It Works

​Supported Entity Types

​Configuration

​Enable Semantic Search

​Embedding Providers

​Docker Deployment

​Kubernetes Deployment

​Validating the Configuration

​Generating Embeddings

​API Reference

​POST /api/v1/search/vector/query

​Troubleshooting

​Semantic Search returns no results

​Embedding generation fails

Enable Semantic Search

Prerequisites

Overview

How It Works

Supported Entity Types

Configuration

Enable Semantic Search

Embedding Providers

Docker Deployment

Kubernetes Deployment

Validating the Configuration

Generating Embeddings

API Reference

POST `/api/v1/search/vector/query`

Troubleshooting

Semantic Search returns no results

Embedding generation fails