llm4s-docs
API
Generated with
llm4s-docs/org.llm4s/org.llm4s.vectorstore/org.llm4s.vectorstore.opensearch

org.llm4s.vectorstore.opensearch

package org.llm4s.vectorstore.opensearch

Members list

Type members

Classlikes

sealed trait OpenSearchAuth

How OpenSearchVectorStore authenticates to the cluster. Credentials are never printed by toString.

How OpenSearchVectorStore authenticates to the cluster. Credentials are never printed by toString.

The security plugin's HTTP basic authentication (its internal user database, as on a self-managed cluster or an Amazon OpenSearch Service domain with fine-grained access control) and bearer tokens (its JWT backend) are supported. AWS Signature Version 4 request signing (IAM) is not.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class Basic
class BearerToken
object NoAuth
object OpenSearchAuth

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class OpenSearchConfig

What OpenSearchVectorStore needs to reach one index of an OpenSearch cluster with the k-NN plugin.

What OpenSearchVectorStore needs to reach one index of an OpenSearch cluster with the k-NN plugin.

Load it from configuration with org.llm4s.config.OpenSearchVectorStoreConfigLoader, which reads llm4s.vectorstore.opensearch, or build one in code:

val config = OpenSearchConfig("https://search.example.com:9200")
 .withIndex("docs")
 .withAuth(OpenSearchAuth.Basic("llm4s", password))
 .withEngine(OpenSearchEngine.Faiss)

The store checks it with OpenSearchConfig#validate when it is built.

Value parameters

auth

the credentials, OpenSearchAuth.NoAuth by default

baseUrl

the cluster's root URL, optionally with a path prefix (a proxy), without a query. It must be https when credentials are sent; plain http is accepted for a loopback host (localhost, 127.0.0.0/8, ::1) or when there are no credentials to protect.

dimensions

the vector size the index is created with; when unset, the size of the first record upserted. When set, a record of another size is refused before it is sent.

efConstruction

the HNSW graph's ef_construction; when unset, the engine's default

engine

the k-NN engine the index is created with; it decides whether filters are applied inside the kNN search (OpenSearchEngine#filtersInsideKnn)

index

the index holding the vectors; OpenSearch's index-name rules apply (lower case, no \ / * ? " < > | , # or space, not starting with -, _ or +)

m

the HNSW graph's m (links per node); when unset, the engine's default

numCandidates

the kNN query's k, the neighbours each shard returns before the result is cut to topK. When unset: topK with efficient filtering, and max(100, 10 * topK) with a post-filter, so that enough candidates survive the filter. Never below topK, at most 10,000.

refreshOnWrite

whether writes wait for a refresh (refresh=wait_for), so that a search straight after an upsert or delete sees it. Turn it off for bulk ingestion.

spaceType

the knn_vector space the index is created with

timeout

how long each HTTP request may take

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object OpenSearchConfig

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
enum OpenSearchEngine(val wireName: String, val filtersInsideKnn: Boolean)

The k-NN library behind a knn_vector field's HNSW graph, fixed when the index is created.

The k-NN library behind a knn_vector field's HNSW graph, fixed when the index is created.

Value parameters

filtersInsideKnn

whether the engine supports efficient filtering - the metadata filter inside the knn query, applied while the graph is searched, so topK results come back when that many match. Without it the filter is applied to the kNN hits afterwards (a post-filter), which can return fewer than topK.

wireName

the value of the mapping's method.engine parameter

Attributes

Companion
object
Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object OpenSearchEngine

Attributes

Companion
enum
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
enum OpenSearchSpaceType(val wireName: String)

The k-NN space a knn_vector field is indexed with, fixed when the index is created.

The k-NN space a knn_vector field is indexed with, fixed when the index is created.

OpenSearch turns each space's distance into a non-negative _score of its own, the same on every OpenSearchEngine. OpenSearchVectorStore maps it onto [0, 1], so that a org.llm4s.vectorstore.ScoredRecord score reads like Elasticsearch's:

  • OpenSearchSpaceType.CosineSimil: OpenSearch's own (2 - (1 - cosine)) / 2 = (1 + cosine) / 2, kept.
  • OpenSearchSpaceType.InnerProduct: (1 + dot) / 2, clamped, from OpenSearch's dot + 1 (for dot >= 0) or 1 / (1 - dot) (for dot < 0). It lies in [0, 1] for unit vectors; other vectors are clamped.
  • OpenSearchSpaceType.L2: OpenSearch's own 1 / (1 + distance^2), already in (0, 1].

Value parameters

wireName

the value of the mapping's space_type parameter

Attributes

Companion
object
Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object OpenSearchSpaceType

Attributes

Companion
enum
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
final class OpenSearchVectorStore extends VectorStore

A org.llm4s.vectorstore.VectorStore over one OpenSearch index with the k-NN plugin, through its REST API and org.llm4s.http.Llm4sHttpClient: no OpenSearch client library is involved.

A org.llm4s.vectorstore.VectorStore over one OpenSearch index with the k-NN plugin, through its REST API and org.llm4s.http.Llm4sHttpClient: no OpenSearch client library is involved.

It shares everything but the vector field and the kNN query with org.llm4s.vectorstore.elasticsearch.ElasticsearchVectorStore - OpenSearch keeps Elasticsearch 7.10's document, _bulk, _mget, _count, _delete_by_query and query DSL APIs - so records, writes, get, list, count, deletes, stats and every org.llm4s.vectorstore.MetadataFilter behave exactly as they do there.

What differs:

  • the index is created on the first upsert with index.knn: true and a knn_vector field sized to OpenSearchConfig#dimensions (or the first record), indexed as an HNSW graph with the configured OpenSearchSpaceType and OpenSearchEngine;
  • search is a knn query. On Lucene and Faiss the metadata filter goes inside it (efficient filtering), so topK results come back when that many match; on NMSLIB, which has no efficient filtering, the filter is applied to the k nearest neighbours afterwards, so a selective filter can return fewer than topK - raise OpenSearchConfig#numCandidates to compensate;
  • each _score is mapped onto [0, 1] per space type, as OpenSearchSpaceType describes;
  • authentication is basic or a bearer token (OpenSearchAuth); AWS SigV4 signing is not supported.

Every operation returns a Result: a transport failure is the client's org.llm4s.error.NetworkError or org.llm4s.error.TimeoutError, a 401 or 403 an org.llm4s.error.AuthenticationError, a 429 a org.llm4s.error.RateLimitError, any other non-2xx status a org.llm4s.error.ServiceError carrying the status and the (redacted) body.

Attributes

Companion
object
Supertypes
trait VectorStore
class Object
trait Matchable
class Any
object OpenSearchVectorStore

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
Generated with