Skip to content

Commit e9d7398

Browse files
Vrryoutzolov
Vrryou
authored and
tzolov
committed
Rewrite Elasticsearch documentation to follow Neo4J's format.
1 parent 9fbc09a commit e9d7398

File tree

1 file changed

+109
-62
lines changed

1 file changed

+109
-62
lines changed

‎spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/elasticsearch.adoc

Lines changed: 109 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -6,42 +6,20 @@ link:https://www.elastic.co/elasticsearch[Elasticsearch] is an open source searc
66

77
== Prerequisites
88

9-
First you need access to an Elasticsearch instance.
10-
11-
On startup, the `ElasticsearchVectorStore` will attempt to create the index mapping.
12-
13-
Optionally, you can do this manually like so:
14-
15-
[source,text]
16-
----
17-
PUT spring-ai-document-index
18-
{
19-
"mappings": {
20-
"properties": {
21-
"embedding": {
22-
"type": "dense_vector",
23-
"dims": 1536,
24-
"index": true,
25-
"similarity": cosine
26-
}
27-
}
28-
}
29-
}
30-
----
31-
32-
TIP: replace the `1536` with the actual embedding dimension if you are using a different dimension.
33-
34-
Next if required, an API key for the xref:api/embeddings.adoc#available-implementations[EmbeddingClient] to generate the embeddings stored by the `ElasticsearchVectorStore`.
9+
* A running Elasticsearch instance. The following options are available:
10+
** link:https://hub.docker.com/_/elasticsearch/[Docker]
11+
** link:https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html#elasticsearch-install-packages[Self-Managed Elasticsearch]
12+
** link:https://www.elastic.co/cloud/elasticsearch-service/signup?page=docs&placement=docs-body[Elastic Cloud]
3513

3614
== Dependencies
3715

38-
Add the ElasticsearchVectorStore boot starter dependency to your project:
16+
Add the Elasticsearch Vector Store dependency to your project:
3917

4018
[source,xml]
4119
----
4220
<dependency>
4321
<groupId>org.springframework.ai</groupId>
44-
<artifactId>spring-ai-elasticsearch-store-spring-boot-starter</artifactId>
22+
<artifactId>spring-ai-elasticsearch-store</artifactId>
4523
</dependency>
4624
----
4725

@@ -50,20 +28,59 @@ or to your Gradle `build.gradle` build file.
5028
[source,groovy]
5129
----
5230
dependencies {
53-
implementation 'org.springframework.ai:spring-ai-elasticsearch-store-spring-boot-starter'
31+
implementation 'org.springframework.ai:spring-ai-elasticsearch-store'
5432
}
5533
----
5634

57-
The Vector Store, also requires an `EmbeddingClient` instance to calculate embeddings for the documents.
58-
You can pick one of the available xref:api/embeddings.adoc#available-implementations[EmbeddingClient Implementations].
35+
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
36+
37+
== Configuration
38+
39+
To connect to Elasticsearch and use the `ElasticsearchVectorStore`, you need to provide access details for your instance.
40+
A simple configuration can either be provided via Spring Boot's `application.yml`,
41+
42+
[source,yaml]
43+
----
44+
spring:
45+
elasticsearch:
46+
uris: <elasticsearch instance URIs>
47+
username: <elasticsearch username>
48+
password: <elasticsearch password>
49+
# API key if needed, e.g. OpenAI
50+
ai:
51+
openai:
52+
api:
53+
key: <api-key>
54+
----
55+
56+
environment variables,
57+
58+
[source,bash]
59+
----
60+
export SPRING_ELASTICSEARCH_URIS=<elasticsearch instance URIs>
61+
export SPRING_ELASTICSEARCH_USERNAME=<elasticsearch username>
62+
export SPRING_ELASTICSEARCH_PASSWORD=<elasticsearch password>
63+
# API key if needed, e.g. OpenAI
64+
export SPRING_AI_OPENAI_API_KEY=<api-key>
65+
----
66+
67+
or can be a mix of those.
68+
For example, if you want to store your password as an environment variable but keep the rest in the plain `application.yml` file.
69+
70+
NOTE: If you choose to create a shell script for ease in future work, be sure to run it prior to starting your application by "sourcing" the file, i.e. `source <your_script_name>.sh`.
71+
72+
Spring Boot's auto-configuration feature for the Elasticsearch RestClient will create a bean instance that will be used by the `ElasticsearchVectorStore`.
5973

60-
For example to use the xref:api/embeddings/openai-embeddings.adoc[OpenAI EmbeddingClient] add the following dependency to your project:
74+
== Auto-configuration
75+
76+
Spring AI provides Spring Boot auto-configuration for the Elasticsearch Vector Store.
77+
To enable it, add the following dependency to your project's Maven `pom.xml` file:
6178

6279
[source,xml]
6380
----
6481
<dependency>
65-
<groupId>org.springframework.ai</groupId>
66-
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
82+
<groupId>org.springframework.ai</groupId>
83+
<artifactId>spring-ai-elasticsearch-store-spring-boot-starter</artifactId>
6784
</dependency>
6885
----
6986

@@ -72,62 +89,92 @@ or to your Gradle `build.gradle` build file.
7289
[source,groovy]
7390
----
7491
dependencies {
75-
implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
92+
implementation 'org.springframework.ai:spring-ai-elasticsearch-store-spring-boot-starter'
7693
}
7794
----
7895

7996
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
80-
Refer to the xref:getting-started.adoc#repositories[Repositories] section to add Milestone and/or Snapshot Repositories to your build file.
8197

82-
To connect to and configure Elasticsearch, you need to provide access details for your instance.
83-
A simple configuration can either be provided via Spring Boot's `application.yml`
98+
Please have a look at the list of <<elasticsearchvector-properties,configuration parameters>> for the vector store to learn about the default values and configuration options.
8499

85-
[source,yaml]
100+
Here is an example of the needed bean:
101+
102+
[source,java]
86103
----
87-
spring:
88-
elasticsearch:
89-
uris: <elasticsearch instance URIs>
90-
username: <elasticsearch username>
91-
password: <elasticsearch password>
92-
ai:
93-
vectorstore:
94-
elasticsearch:
95-
index-name: spring-ai-index
104+
@Bean
105+
public EmbeddingClient embeddingCLient() {
106+
// Can be any other EmbeddingClient implementation
107+
return new OpenAiEmbeddingClient(new OpenAiApi(System.getenv("SPRING_AI_OPENAI_API_KEY")));
108+
}
96109
----
97110

98-
TIP: Check the list of <<elasticsearchvector-properties, configuration parameters>> to learn about the default values and configuration options.
99-
100-
In your main code, create some documents:
111+
In cases where the Spring Boot auto-configured Elasticsearch `RestClient` bean is not what you want or need, you can still define your own bean.
112+
Please read the link:https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/java-rest-low-usage-initialization.html[Elasticsearch Documentation]
113+
for more in-depth information about the configuration of a custom RestClient.
101114

102115
[source,java]
103116
----
104-
List<Document> documents = List.of(
105-
new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
106-
new Document("The World is Big and Salvation Lurks Around the Corner"),
107-
new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));
117+
@Bean
118+
public RestClient restClienbt() {
119+
RestClientBuilder builder = RestClient.builder(new HttpHost("<host>", 9200, "http"));
120+
Header[] defaultHeaders = new Header[] { new BasicHeader("Authorization", "Basic <encoded username and password>") };
121+
builder.setDefaultHeaders(defaultHeaders);
122+
return builder.build();
123+
}
108124
----
109125

110-
Add the documents to Elasticsearch:
126+
Now you can auto-wire the `ElasticsearchVectorStore` as a vector store in your application.
127+
128+
== Metadata Filtering
129+
130+
You can leverage the generic, portable xref:api/vectordbs.adoc#metadata-filters[metadata filters] with Elasticsearcg as well.
131+
132+
For example, you can use either the text expression language:
111133

112134
[source,java]
113135
----
114-
vectorStore.add(List.of(document));
136+
vectorStore.similaritySearch(SearchRequest.defaults()
137+
.withQuery("The World")
138+
.withTopK(TOP_K)
139+
.withSimilarityThreshold(SIMILARITY_THRESHOLD)
140+
.withFilterExpression("author in ['john', 'jill'] && 'article_type' == 'blog'"));
115141
----
116142

117-
And finally, retrieve documents similar to a query:
143+
or programmatically using the `Filter.Expression` DSL:
118144

119145
[source,java]
120146
----
121-
List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
147+
FilterExpressionBuilder b = new FilterExpressionBuilder();
148+
149+
vectorStore.similaritySearch(SearchRequest.defaults()
150+
.withQuery("The World")
151+
.withTopK(TOP_K)
152+
.withSimilarityThreshold(SIMILARITY_THRESHOLD)
153+
.withFilterExpression(b.and(
154+
b.in("john", "jill"),
155+
b.eq("article_type", "blog")).build()));
122156
----
123157

124-
If all goes well, you should retrieve the document containing the text "Spring AI rocks!!".
158+
NOTE: Those (portable) filter expressions get automatically converted into the proprietary Elasticsearch `WHERE` link:https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-syntax-select.html#sql-syntax-where[filter expressions].
159+
160+
For example, this portable filter expression:
161+
162+
[source,sql]
163+
----
164+
author in ['john', 'jill'] && 'article_type' == 'blog'
165+
----
166+
167+
is converted into the proprietary Elasticsearch filter format:
168+
169+
[source,text]
170+
----
171+
(metadata.author:john OR jill) AND metadata.article_type:blog
172+
----
125173

126174
[[elasticsearchvector-properties]]
127175
== ElasticsearchVectorStore Properties
128176

129-
You can use the following properties in your Spring Boot configuration to customize the Elasticsearch Vector Store.
130-
177+
You can use the following properties in your Spring Boot configuration to customize the Elasticsearch vector store.
131178

132179
|===
133180
|Property |Default Value

0 commit comments

Comments
 (0)