Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

current opensearch component code from flows

Edwin Josede196d360678
diff --git a/flows/components/opensearch_multimodal.py b/flows/components/opensearch_multimodal.py
index c3d42b1ca..8a2407a52 100644
--- a/flows/components/opensearch_multimodal.py
+++ b/flows/components/opensearch_multimodal.py
@@ -12,7 +12,6 @@ from opensearchpy.exceptions import OpenSearchException, RequestError
from lfx.base.vectorstores.model import LCVectorStoreComponent, check_cached_vector_store
from lfx.base.vectorstores.vector_store_connection_decorator import vector_store_connection
-
from lfx.io import (
BoolInput,
DropdownInput,
@@ -27,6 +26,9 @@ from lfx.io import (
from lfx.log import logger
from lfx.schema.data import Data
+REQUEST_TIMEOUT = 60
+MAX_RETRIES = 5
+
def normalize_model_name(model_name: str) -> str:
"""Normalize embedding model name for use as field suffix.
@@ -125,6 +127,8 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
"m",
"num_candidates",
"docs_metadata",
+ "request_timeout",
+ "max_retries",
]
inputs = [
@@ -173,11 +177,12 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
DropdownInput(
name="engine",
display_name="Vector Engine",
- options=["jvector", "nmslib", "faiss", "lucene"],
+ options=["nmslib", "faiss", "lucene", "jvector"],
value="jvector",
info=(
- "Vector search engine for similarity calculations. 'jvector' is recommended for most use cases. "
- "Note: Amazon OpenSearch Serverless only supports 'nmslib' or 'faiss'."
+ "Vector search engine for similarity calculations. 'nmslib' works with standard "
+ "OpenSearch. 'jvector' requires OpenSearch 2.9+. 'lucene' requires index.knn: true. "
+ "Amazon OpenSearch Serverless only supports 'nmslib' or 'faiss'."
),
advanced=True,
),
@@ -339,7 +344,24 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
"Disable for self-signed certificates in development environments."
),
),
- # DictInput(name="query", display_name="Query", input_types=["Data"], is_list=False, tool_mode=True),
+ # ----- Timeout / Retry -----
+ StrInput(
+ name="request_timeout",
+ display_name="Request Timeout (seconds)",
+ value="60",
+ advanced=True,
+ info=(
+ "Time in seconds to wait for a response from OpenSearch. "
+ "Increase for large bulk ingestion or complex hybrid queries."
+ ),
+ ),
+ StrInput(
+ name="max_retries",
+ display_name="Max Retries",
+ value="3",
+ advanced=True,
+ info="Number of retries for failed connections before raising an error.",
+ ),
]
outputs = [
Output(
@@ -350,7 +372,7 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
Output(display_name="Raw Search", name="raw_search", method="raw_search"),
]
- def raw_search(self, query: str | None = None) -> Data:
+ def raw_search(self, query: str | dict | None = None) -> Data:
"""Execute a raw OpenSearch query against the target index.
Args:
@@ -363,13 +385,40 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
ValueError: If 'query' is not a valid OpenSearch query (must be a non-empty dict).
"""
raw_query = query if query is not None else self.search_query
- if isinstance(raw_query, str):
- raw_query = json.loads(raw_query)
+
+ if raw_query is None or (isinstance(raw_query, str) and not raw_query.strip()):
+ self.log("No query provided for raw search - returning empty results")
+ return Data(data={})
+
+ if isinstance(raw_query, dict):
+ query_body = raw_query
+ elif isinstance(raw_query, str):
+ s = raw_query.strip()
+
+ # First, optimistically try to parse as JSON DSL
+ try:
+ query_body = json.loads(s)
+ except json.JSONDecodeError:
+ # Fallback: treat as a basic text query over common fields
+ query_body = {
+ "query": {
+ "multi_match": {
+ "query": s,
+ "fields": ["text^2", "filename^1.5"],
+ "type": "best_fields",
+ "fuzziness": "AUTO",
+ }
+ }
+ }
+ else:
+ msg = f"Unsupported raw_search query type: {type(raw_query)!r}"
+ raise TypeError(msg)
+
client = self.build_client()
- logger.info(f"query: {raw_query}")
+ logger.info(f"query: {query_body}")
resp = client.search(
index=self.index_name,
- body=raw_query,
+ body=query_body,
params={"terminate_after": 0},
)
# Remove any _source keys whose value is a list of floats (embedding vectors)
@@ -547,7 +596,7 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
)
else:
logger.info(
- f"[OpenSearchMultimodal] Field '{field_name}' already exists"
+ f"[OpenSearchMultimodel] Field '{field_name}' already exists"
f"as knn_vector with matching dimensions - skipping mapping update"
)
return
@@ -573,20 +622,35 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
}
client.indices.put_mapping(index=index_name, body=mapping)
logger.info(f"Added/updated embedding field mapping: {field_name}")
+ except RequestError as e:
+ error_str = str(e).lower()
+ if "invalid engine" in error_str and "jvector" in error_str:
+ msg = (
+ "The 'jvector' engine is not available in your OpenSearch installation. "
+ "Use 'nmslib' or 'faiss' for standard OpenSearch, or upgrade to OpenSearch 2.9+."
+ )
+ raise ValueError(msg) from e
+ if "index.knn" in error_str:
+ msg = (
+ "The index has index.knn: false. Delete the existing index and let the "
+ "component recreate it, or create a new index with a different name."
+ )
+ raise ValueError(msg) from e
+ raise
except Exception as e:
# Check if this is the known OpenSearch k-NN NullPointerException issue
error_str = str(e).lower()
if "null" in error_str or "nullpointerexception" in error_str:
logger.warning(
- f"[OpenSearchMultimodal] Could not add embedding field mapping for {field_name}"
+ f"[OpenSearchMultimodel] Could not add embedding field mapping for {field_name}"
f"due to OpenSearch k-NN plugin issue: {e}. "
f"This is a known issue with some OpenSearch versions. "
- f"[OpenSearchMultimodal] Skipping mapping update. "
+ f"[OpenSearchMultimodel] Skipping mapping update. "
f"Please ensure the index has the correct mapping for KNN search to work."
)
# Skip and continue - ingestion will proceed, but KNN search may fail if mapping doesn't exist
return
- logger.warning(f"[OpenSearchMultimodal] Could not add embedding field mapping for {field_name}: {e}")
+ logger.warning(f"[OpenSearchMultimodel] Could not add embedding field mapping for {field_name}: {e}")
raise
# Verify the field was added correctly
@@ -663,7 +727,7 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
Returns:
List of document IDs that were successfully ingested
"""
- logger.debug(f"[OpenSearchMultimodal] Bulk ingesting embeddings for {index_name}")
+ logger.debug(f"[OpenSearchMultimodel] Bulk ingesting embeddings for {index_name}")
if not mapping:
mapping = {}
@@ -708,6 +772,24 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
helpers.bulk(client, requests, max_chunk_bytes=max_chunk_bytes)
return return_ids
+ # ---------- param helpers ----------
+ def _parse_int_param(self, attr_name: str, default: int) -> int:
+ """Parse a string attribute to int, returning *default* on failure."""
+ raw = getattr(self, attr_name, None)
+ if raw is None or str(raw).strip() == "":
+ return default
+ try:
+ value = int(str(raw).strip())
+ except ValueError:
+ logger.warning(f"Invalid integer value '{raw}' for {attr_name}, using default {default}")
+ return default
+
+ if value < 0:
+ logger.warning(f"Negative value '{raw}' for {attr_name}, using default {default}")
+ return default
+
+ return value
+
# ---------- auth / client ----------
def _build_auth_kwargs(self) -> dict[str, Any]:
"""Build authentication configuration for OpenSearch client.
@@ -743,7 +825,7 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
Returns:
Configured OpenSearch client ready for operations
"""
- logger.debug("[OpenSearchMultimodal] Building OpenSearch client")
+ logger.debug("[OpenSearchMultimodel] Building OpenSearch client")
auth_kwargs = self._build_auth_kwargs()
return OpenSearch(
hosts=[self.opensearch_url],
@@ -751,6 +833,9 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
verify_certs=self.verify_certs,
ssl_assert_hostname=False,
ssl_show_warn=False,
+ timeout=self._parse_int_param("request_timeout", REQUEST_TIMEOUT),
+ max_retries=self._parse_int_param("max_retries", MAX_RETRIES),
+ retry_on_timeout=True,
**auth_kwargs,
)
@@ -762,10 +847,10 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
# Check if we're in ingestion-only mode (no search query)
has_search_query = bool((self.search_query or "").strip())
if not has_search_query:
- logger.debug("[OpenSearchMultimodal] Ingestion-only mode activated: search operations will be skipped")
- logger.debug("[OpenSearchMultimodal] Starting ingestion mode...")
+ logger.debug("[OpenSearchMultimodel] Ingestion-only mode activated: search operations will be skipped")
+ logger.debug("[OpenSearchMultimodel] Starting ingestion mode...")
- logger.debug(f"[OpenSearchMultimodal] Embedding: {self.embedding}")
+ logger.debug(f"[OpenSearchMultimodel] Embedding: {self.embedding}")
self._add_documents_to_vector_store(client=client)
return client
@@ -782,16 +867,16 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
Args:
client: OpenSearch client for performing operations
"""
- logger.debug("[OpenSearchMultimodal][INGESTION] _add_documents_to_vector_store called")
+ logger.debug("[OpenSearchMultimodel][INGESTION] _add_documents_to_vector_store called")
# Convert DataFrame to Data if needed using parent's method
self.ingest_data = self._prepare_ingest_data()
logger.debug(
- f"[OpenSearchMultimodal][INGESTION] ingest_data type: "
+ f"[OpenSearchMultimodel][INGESTION] ingest_data type: "
f"{type(self.ingest_data)}, length: {len(self.ingest_data) if self.ingest_data else 0}"
)
logger.debug(
- f"[OpenSearchMultimodal][INGESTION] ingest_data content: "
+ f"[OpenSearchMultimodel][INGESTION] ingest_data content: "
f"{self.ingest_data[:2] if self.ingest_data and len(self.ingest_data) > 0 else 'empty'}"
)
@@ -816,8 +901,8 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
self.log("Embedding returned None (fail-safe mode enabled). Skipping document ingestion.")
return
- logger.debug(f"[OpenSearchMultimodal][INGESTION] Valid embeddings after filtering: {len(embeddings_list)}")
- self.log(f"[OpenSearchMultimodal][INGESTION] Available embedding models: {len(embeddings_list)}")
+ logger.debug(f"[OpenSearchMultimodel][INGESTION] Valid embeddings after filtering: {len(embeddings_list)}")
+ self.log(f"[OpenSearchMultimodel][INGESTION] Available embedding models: {len(embeddings_list)}")
# Select the embedding to use for ingestion
selected_embedding = None
@@ -1101,14 +1186,31 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
vector_field=dynamic_field_name, # Use dynamic field name
)
- # Ensure index exists with baseline mapping
+ # Ensure index exists with baseline mapping (index.knn: true is required for vector search)
try:
if not client.indices.exists(index=self.index_name):
self.log(f"Creating index '{self.index_name}' with base mapping")
client.indices.create(index=self.index_name, body=mapping)
except RequestError as creation_error:
- if creation_error.error != "resource_already_exists_exception":
+ if creation_error.error == "resource_already_exists_exception":
+ pass # Index was created concurrently
+ else:
+ error_msg = str(creation_error).lower()
+ if "invalid engine" in error_msg or "illegal_argument" in error_msg:
+ if "jvector" in error_msg:
+ msg = (
+ "The 'jvector' engine is not available in your OpenSearch installation. "
+ "Use 'nmslib' or 'faiss' for standard OpenSearch, or upgrade to 2.9+."
+ )
+ raise ValueError(msg) from creation_error
+ if "index.knn" in error_msg:
+ msg = (
+ "The index has index.knn: false. Delete the existing index and let the "
+ "component recreate it, or create a new index with a different name."
+ )
+ raise ValueError(msg) from creation_error
logger.warning(f"Failed to create index '{self.index_name}': {creation_error}")
+ raise
# Ensure the dynamic field exists in the index
self._ensure_embedding_field_mapping(
@@ -1330,6 +1432,29 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
return None
+ def _get_filename_agg_field(self, index_properties: dict[str, Any] | None) -> str:
+ """Choose the appropriate field for filename aggregations."""
+ if not index_properties:
+ return "filename.keyword"
+
+ filename_def = index_properties.get("filename")
+ if not isinstance(filename_def, dict):
+ return "filename.keyword"
+
+ field_type = filename_def.get("type")
+ fields_def = filename_def.get("fields", {})
+
+ # Top-level keyword with no subfields
+ if field_type == "keyword" and not isinstance(fields_def, dict):
+ return "filename"
+
+ # Text field with keyword subfield
+ if isinstance(fields_def, dict) and "keyword" in fields_def:
+ return "filename.keyword"
+
+ # Fallback: aggregate on filename directly
+ return "filename"
+
# ---------- search (multi-model hybrid) ----------
def search(self, query: str | None = None) -> list[dict[str, Any]]:
"""Perform multi-model hybrid search combining multiple vector similarities and keyword matching.
@@ -1614,152 +1739,22 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
knn_queries_with_candidates.append(query_with_candidates)
knn_queries_without_candidates.append(base_query)
- # Get limit and score threshold
- limit = (filter_obj or {}).get("limit", self.number_of_results)
- score_threshold = (filter_obj or {}).get("score_threshold", 0)
-
- # Build keyword-only body once so we can gracefully fallback from KNN errors.
- keyword_only_body = {
- "query": {
- "bool": {
- "must": [
- {
- "multi_match": {
- "query": q,
- "fields": ["text^2", "filename^1.5"],
- "type": "best_fields",
- "fuzziness": "AUTO",
- }
- }
- ],
- "filter": filter_clauses,
- }
- },
- "aggs": {
- "data_sources": {"terms": {"field": "filename.keyword", "size": 20}},
- "document_types": {"terms": {"field": "mimetype.keyword", "size": 10}},
- "owners": {"terms": {"field": "owner.keyword", "size": 10}},
- "embedding_models": {"terms": {"field": "embedding_model", "size": 10}},
- },
- "_source": [
- "filename",
- "mimetype",
- "page",
- "text",
- "source_url",
- "owner",
- "embedding_model",
- "allowed_users",
- "allowed_groups",
- ],
- "size": limit,
- }
- if isinstance(score_threshold, (int, float)) and score_threshold > 0:
- keyword_only_body["min_score"] = score_threshold
-
- def run_keyword_fallback(reason: str):
- if not q:
- # Keep empty-query behavior deterministic: do not run multi_match("")
- # during fallback paths, which can otherwise return broad/unexpected hits.
- self.log("[FALLBACK] Empty query detected; returning no results.")
- return {"hits": {"hits": []}}
- logger.warning(
- "Falling back to keyword-only OpenSearch retrieval",
- reason=reason,
- )
- self.log(f"[FALLBACK] Keyword-only retrieval: {reason}")
- try:
- return client.search(
- index=self.index_name,
- body=keyword_only_body,
- params={"terminate_after": 0},
- )
- except RequestError as fallback_error:
- fallback_message = str(fallback_error).lower()
- if "text fields are not optimised" in fallback_message or "fielddata" in fallback_message:
- # Some clusters still reject terms aggs on text fields if mappings are inconsistent.
- # Keep retrieval working by retrying without aggregations.
- fallback_without_aggs = copy.deepcopy(keyword_only_body)
- fallback_without_aggs.pop("aggs", None)
- return client.search(
- index=self.index_name,
- body=fallback_without_aggs,
- params={"terminate_after": 0},
- )
- raise
-
- def run_legacy_vector_fallback(reason: str):
- fallback_vector = next(iter(query_embeddings.values()), None)
- if fallback_vector is None:
- return run_keyword_fallback(f"{reason}; no query embeddings available")
-
- fallback_field = legacy_vector_field or "chunk_embedding"
- logger.warning(
- "KNN search failed for dynamic fields; falling back to legacy field '%s'.",
- fallback_field,
- )
- self.log(f"[FALLBACK] Legacy vector fallback: field={fallback_field}; reason={reason}")
-
- fallback_body = copy.deepcopy(body)
- # Keep user filters and explicitly require the legacy embedding field to exist.
- # This avoids returning documents without embeddings during semantic fallback.
- try:
- bool_query = fallback_body["query"]["bool"]
- except (KeyError, TypeError):
- return run_keyword_fallback(
- f"{reason}; legacy fallback query missing query.bool structure"
- )
- bool_query["filter"] = [
- *filter_clauses,
- {"exists": {"field": fallback_field}},
- ]
- knn_fallback = {
- "knn": {
- fallback_field: {
- "vector": fallback_vector,
- "k": 50,
- }
- }
- }
- if use_num_candidates:
- knn_fallback["knn"][fallback_field]["num_candidates"] = num_candidates
- try:
- bool_query["should"][0]["dis_max"]["queries"] = [knn_fallback]
- except (KeyError, IndexError, TypeError):
- return run_keyword_fallback(
- f"{reason}; legacy fallback query missing bool.should/dis_max structure"
- )
-
- return client.search(
- index=self.index_name,
- body=fallback_body,
- params={"terminate_after": 0},
- )
-
if not knn_queries_with_candidates:
# No valid fields found - this can happen when:
# 1. Index is empty (no documents yet)
- # 2. KNN mappings are missing/broken for current embedding model
+ # 2. Embedding model has changed and field doesn't exist yet
+ # Return empty results instead of failing
logger.warning(
"No valid knn_vector fields found for embedding models. "
- "Falling back to keyword-only retrieval."
+ "This may indicate an empty index or missing field mappings. "
+ "Returning empty search results."
)
self.log(
f"[WARN] No valid KNN queries could be built. "
f"Query embeddings generated: {list(query_embeddings.keys())}, "
f"but no matching knn_vector fields found in index."
)
- resp = run_keyword_fallback("no valid knn_vector fields available")
- hits = resp.get("hits", {}).get("hits", [])
- logger.info(f"Found {len(hits)} results (keyword fallback)")
- return [
- {
- "page_content": hit["_source"].get("text", ""),
- "metadata": {k: v for k, v in hit["_source"].items() if k != "text"},
- "score": hit.get("_score"),
- }
- for hit in hits
- ]
+ return []
# Build exists filter - document must have at least one embedding field
exists_any_embedding = {
@@ -1769,6 +1764,13 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
# Combine user filters with exists filter
all_filters = [*filter_clauses, exists_any_embedding]
+ # Get limit and score threshold
+ limit = (filter_obj or {}).get("limit", self.number_of_results)
+ score_threshold = (filter_obj or {}).get("score_threshold", 0)
+
+ # Determine the best aggregation field for filename based on index mapping
+ filename_agg_field = self._get_filename_agg_field(index_properties)
+
# Build multi-model hybrid query
body = {
"query": {
@@ -1796,9 +1798,9 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
}
},
"aggs": {
- "data_sources": {"terms": {"field": "filename.keyword", "size": 20}},
- "document_types": {"terms": {"field": "mimetype.keyword", "size": 10}},
- "owners": {"terms": {"field": "owner.keyword", "size": 10}},
+ "data_sources": {"terms": {"field": filename_agg_field, "size": 20}},
+ "document_types": {"terms": {"field": "mimetype", "size": 10}},
+ "owners": {"terms": {"field": "owner", "size": 10}},
"embedding_models": {"terms": {"field": "embedding_model", "size": 10}},
},
"_source": [
@@ -1841,25 +1843,38 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
fallback_body["query"]["bool"]["should"][0]["dis_max"]["queries"] = knn_queries_without_candidates
except (KeyError, IndexError, TypeError) as inner_err:
raise e from inner_err
- try:
- resp = client.search(
- index=self.index_name,
- body=fallback_body,
- params={"terminate_after": 0},
- )
- except RequestError as retry_error:
- retry_error_message = str(retry_error)
- retry_lowered = retry_error_message.lower()
- if "knn_vector" in retry_lowered or ("field" in retry_lowered and "knn" in retry_lowered):
- resp = run_legacy_vector_fallback(
- f"search failed after num_candidates retry: {retry_error_message}"
- )
- else:
- resp = run_keyword_fallback(
- f"search failed after num_candidates retry: {retry_error_message}"
- )
+ resp = client.search(
+ index=self.index_name,
+ body=fallback_body,
+ params={"terminate_after": 0},
+ )
elif "knn_vector" in lowered or ("field" in lowered and "knn" in lowered):
- resp = run_legacy_vector_fallback(f"knn query error: {error_message}")
+ fallback_vector = next(iter(query_embeddings.values()), None)
+ if fallback_vector is None:
+ raise
+ fallback_field = legacy_vector_field or "chunk_embedding"
+ logger.warning(
+ "KNN search failed for dynamic fields; falling back to legacy field '%s'.",
+ fallback_field,
+ )
+ fallback_body = copy.deepcopy(body)
+ fallback_body["query"]["bool"]["filter"] = filter_clauses
+ knn_fallback = {
+ "knn": {
+ fallback_field: {
+ "vector": fallback_vector,
+ "k": 50,
+ }
+ }
+ }
+ if use_num_candidates:
+ knn_fallback["knn"][fallback_field]["num_candidates"] = num_candidates
+ fallback_body["query"]["bool"]["should"][0]["dis_max"]["queries"] = [knn_fallback]
+ resp = client.search(
+ index=self.index_name,
+ body=fallback_body,
+ params={"terminate_after": 0},
+ )
else:
raise
hits = resp.get("hits", {}).get("hits", [])
@@ -1954,9 +1969,12 @@ class OpenSearchVectorStoreComponentMultimodalMultiEmbedding(LCVectorStoreCompon
build_config["jwt_header"]["required"] = is_jwt
build_config["bearer_prefix"]["required"] = False
+ if is_basic:
+ build_config["jwt_token"]["value"] = ""
+
return build_config
except (KeyError, ValueError) as e:
self.log(f"update_build_config error: {e}")
- return build_config
\ No newline at end of file
+ return build_config
diff --git a/flows/components/opensearch_multimodel.py b/flows/components/opensearch_multimodel.py
deleted file mode 100644
index e69de29bb..000000000