Data store

OpenSearch data store with capability composition.

Authors

Kadek Denaya (kadek.d.r.diana@gdplabs.id)

References

NONE

OpenSearchDataStore(index_name, client=None, url=None, cloud_id=None, api_key=None, username=None, password=None, request_timeout=DEFAULT_REQUEST_TIMEOUT, connection_params=None)

Bases: BaseDataStore

OpenSearch data store with multiple capability support.

This is the explicit public API for OpenSearch. Users know they're using OpenSearch, not a generic "elastic-like" datastore.

Attributes:

Name	Type	Description
engine	str	Always "opensearch" for explicit identification. This attribute ensures users know they're using OpenSearch, not a generic "elastic-like" datastore.
index_name	str	The name of the OpenSearch index.
client	AsyncOpenSearch	AsyncOpenSearch client.

Initialize the OpenSearch data store.

Parameters:

Name	Type	Description	Default
index_name	str	The name of the OpenSearch index to use for operations. This index name will be used for all queries and operations.	required
client	AsyncOpenSearch | None	Pre-configured OpenSearch client instance. If provided, it will be used instead of creating a new client from url/cloud_id. Must be an instance of AsyncOpenSearch. Defaults to None.	None
url	str | None	The URL of the OpenSearch server. For example, "http://localhost:9200". Either url or cloud_id must be provided if client is None. Defaults to None.	None
cloud_id	str | None	The cloud ID of the OpenSearch cluster. Used for OpenSearch Service connections. Either url or cloud_id must be provided if client is None. Defaults to None.	None
api_key	str | None	The API key for authentication. If provided, will be used for authentication. Mutually exclusive with username/password. Defaults to None.	None
username	str | None	The username for basic authentication. Must be provided together with password. Mutually exclusive with api_key. Defaults to None.	None
password	str | None	The password for basic authentication. Must be provided together with username. Mutually exclusive with api_key. Defaults to None.	None
request_timeout	int	The request timeout in seconds. Defaults to DEFAULT_REQUEST_TIMEOUT.	DEFAULT_REQUEST_TIMEOUT
connection_params	dict[str, Any] | None	Additional connection parameters for OpenSearch client. These will be merged with automatically detected parameters (authentication, SSL settings). User-provided params take precedence. Defaults to None. Available parameters include: 1. http_auth (tuple[str, str] | None): HTTP authentication tuple (username, password). 2. use_ssl (bool): Whether to use SSL/TLS. Defaults to True for HTTPS URLs. 3. verify_certs (bool): Whether to verify SSL certificates. Defaults to True for HTTPS URLs. Set to False to use self-signed certificates (not recommended for production). 4. ssl_show_warn (bool): Whether to show SSL warnings. Defaults to True for HTTPS URLs. 5. ssl_assert_hostname (str | None): SSL hostname assertion. Defaults to None. 6. max_retries (int): Maximum number of retries for requests. Defaults to 3. 7. retry_on_timeout (bool): Whether to retry on timeouts. Defaults to True. 8. client_cert (str | None): Path to the client certificate file. Defaults to None. 9. client_key (str | None): Path to the client private key file. Defaults to None. 10. root_cert (str | None): Path to the root certificate file. Defaults to None. 11. Additional kwargs: Any other parameters accepted by OpenSearch client constructor.	None

Raises:

Type	Description
ValueError	If neither url nor cloud_id is provided when client is None.
TypeError	If client is provided but is not an instance of AsyncOpenSearch.

fulltext property

Access fulltext capability if supported.

This method uses the logic of its parent class to return the fulltext capability handler. This method overrides the parent class to return the OpenSearchFulltextCapability handler for better type hinting.

Returns:

Name	Type	Description
OpenSearchFulltextCapability	OpenSearchFulltextCapability	Fulltext capability handler.

Raises:

Type	Description
NotSupportedException	If fulltext capability is not supported.

supported_capabilities property

Return list of currently supported capabilities.

Returns:

Type	Description
list[str]	list[str]: List of capability names that are supported. Currently returns [CapabilityType.FULLTEXT, CapabilityType.VECTOR].

vector property

Access vector capability if supported.

This method uses the logic of its parent class to return the vector capability handler. This method overrides the parent class to return the OpenSearchVectorCapability handler for better type hinting.

Returns:

Name	Type	Description
OpenSearchVectorCapability	OpenSearchVectorCapability	Vector capability handler.

Raises:

Type	Description
NotSupportedException	If vector capability is not supported.

translate_query_filter(query_filter, **kwargs) classmethod

Translate QueryFilter or FilterClause to OpenSearch native filter syntax.

This method delegates to the OpenSearchQueryTranslator and returns the result as a dictionary.

Parameters:

Name	Type	Description	Default
query_filter	FilterClause | QueryFilter	The filter to translate. Can be a single FilterClause, a QueryFilter with multiple clauses and logical conditions. FilterClause objects are automatically converted to QueryFilter.	required
**kwargs	Any	Additional parameters (unused, kept for compatibility with base class).	{}

Returns:

Type	Description
dict[str, Any] | None	dict[str, Any] | None: The translated filter as an OpenSearch DSL dictionary. Returns None for empty filters. The dictionary format matches OpenSearch Query DSL syntax.

with_encryption(encryptor, fields)

Enable encryption for specified fields.

Note

Encrypted fields (content and metadata fields specified in encryption configuration) must be serializable to strings. Non-string values will be converted to strings before encryption.

Warning

When encryption is enabled for fields, some search and filter operations may be limited or broken. Encrypted fields cannot be used in filters for update or delete operations, as the filter values are not encrypted and will not match the encrypted data stored in the index. Use non-encrypted fields (like 'id') for filtering when working with encrypted data.

Parameters:

Name	Type	Description	Default
encryptor	BaseEncryptor	The encryptor instance to use. Must not be None.	required
fields	set[str] | list[str]	Set or list of field names to encrypt. Must not be empty.	required

Returns:

Name	Type	Description
OpenSearchDataStore	OpenSearchDataStore	Self for method chaining.

Raises:

Type	Description
ValueError	If encryptor is None or fields is empty.

with_fulltext(index_name=None, query_field='text')

Configure fulltext capability and return datastore instance.

Overrides parent for better type hinting.

Parameters:

Name	Type	Description	Default
index_name	str | None	Index name for fulltext operations. Uses datastore's default if None. Defaults to None.	None
query_field	str	Field name for text queries. Defaults to "text".	'text'

Returns:

Name	Type	Description
OpenSearchDataStore	OpenSearchDataStore	Self for method chaining.

with_vector(em_invoker, index_name=None, query_field='text', vector_query_field='vector', retrieval_strategy=None, distance_strategy=None)

Configure vector capability and return datastore instance.

Overrides parent for better type hinting.

Parameters:

Name	Type	Description	Default
em_invoker	BaseEMInvoker	Embedding model for vectorization.	required
index_name	str | None	Index name. Uses datastore's default if None.	None
query_field	str	Field name for text queries. Defaults to "text".	'text'
vector_query_field	str	Field name for vector queries. Defaults to "vector".	'vector'
retrieval_strategy	Any	Not used (kept for API compatibility). Defaults to None.	None
distance_strategy	str | None	Distance strategy (e.g., "l2", "cosine"). Defaults to None.	None

Returns:

Name	Type	Description
OpenSearchDataStore	OpenSearchDataStore	Self for method chaining.

Note

Connection parameters are configured at the data store level during initialization. See OpenSearchDataStore.init for connection_params details.