Skip to content

Commit 7227dae

Browse files
sophialagerkranspandeysophialagerkranspandey
authored
Merge pull request #188 from azaddhirajkumar/Add-Couchbase-Vector-Store-Connector
Add Couchbase Vector Store Connector
2 parents 5845ac9 + c7ee2ff commit 7227dae

File tree

3 files changed

+260
-0
lines changed

3 files changed

+260
-0
lines changed

‎semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
href: azure-cosmosdb-mongodb-connector.md
77
- name: Azure CosmosDB NoSQL connector
88
href: azure-cosmosdb-nosql-connector.md
9+
- name: Couchbase connector
10+
href: couchbase-connector.md
911
- name: Elasticsearch connector
1012
href: elasticsearch-connector.md
1113
- name: In-memory connector

‎semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/couchbase-connector.md

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
---
2+
title: Using the Semantic Kernel Couchbase Vector Store connector (Preview)
3+
description: Contains information on how to use a Semantic Kernel Vector store connector to access and manipulate data in Couchbase.
4+
zone_pivot_groups: programming-languages
5+
author: azaddhirajkumar
6+
ms.topic: conceptual
7+
ms.author: westey
8+
ms.date: 01/14/2025
9+
ms.service: semantic-kernel
10+
---
11+
12+
# Using the Couchbase connector (Preview)
13+
14+
> [!WARNING]
15+
> The Semantic Kernel Vector Store functionality is in preview, and improvements that require breaking changes may still occur in limited circumstances before release.
16+
17+
::: zone pivot="programming-language-csharp"
18+
19+
## Overview
20+
21+
The Couchbase Vector Store connector can be used to access and manage data in Couchbase. The connector has the
22+
following characteristics.
23+
24+
| Feature Area | Support |
25+
|---------------------------------------|-------------------------------------------------------------------------------------------------------------------|
26+
| Collection maps to | Couchbase collection |
27+
| Supported key property types | string |
28+
| Supported data property types | All types that are supported by System.Text.Json (either built-in or by using a custom converter) |
29+
| Supported vector property types | <ul><li>ReadOnlyMemory\<float\></li></ul> |
30+
| Supported index types | N/A |
31+
| Supported distance functions | <ul><li>CosineSimilarity</li><li>DotProductSimilarity</li><li>EuclideanDistance</li></ul> |
32+
| Supported filter clauses | <ul><li>AnyTagEqualTo</li><li>EqualTo</li></ul> |
33+
| Supports multiple vectors in a record | Yes |
34+
| IsFilterable supported? | No |
35+
| IsFullTextSearchable supported? | No |
36+
| StoragePropertyName supported? | No, use `JsonSerializerOptions` and `JsonPropertyNameAttribute` instead. [See here for more info.](#data-mapping) |
37+
38+
## Getting Started
39+
40+
Add the Couchbase Vector Store connector NuGet package to your project.
41+
42+
```dotnetcli
43+
dotnet add package CouchbaseConnector.SemanticKernel --prerelease
44+
```
45+
46+
You can add the vector store to the dependency injection container available on the `KernelBuilder` or to
47+
the `IServiceCollection` dependency injection container using extension methods provided by Semantic Kernel.
48+
49+
```csharp
50+
using Microsoft.SemanticKernel;
51+
52+
// Using Kernel Builder.
53+
var kernelBuilder = Kernel.CreateBuilder()
54+
.AddCouchbaseVectorStore(
55+
connectionString: "couchbases://your-cluster-address",
56+
username: "username",
57+
password: "password",
58+
bucketName: "bucket-name",
59+
scopeName: "scope-name");
60+
```
61+
62+
```csharp
63+
using Microsoft.Extensions.DependencyInjection;
64+
65+
// Using IServiceCollection with ASP.NET Core.
66+
var builder = WebApplication.CreateBuilder(args);
67+
builder.Services.AddCouchbaseVectorStore(
68+
connectionString: "couchbases://your-cluster-address",
69+
username: "username",
70+
password: "password",
71+
bucketName: "bucket-name",
72+
scopeName: "scope-name");
73+
```
74+
75+
Extension methods that take no parameters are also provided. These require an instance of the `IScope` class to be
76+
separately registered with the dependency injection container.
77+
78+
```csharp
79+
using Microsoft.Extensions.DependencyInjection;
80+
using Microsoft.SemanticKernel;
81+
using Couchbase;
82+
using Couchbase.KeyValue;
83+
84+
// Using Kernel Builder.
85+
var kernelBuilder = Kernel.CreateBuilder();
86+
kernelBuilder.Services.AddSingleton<ICluster>(sp =>
87+
{
88+
var clusterOptions = new ClusterOptions
89+
{
90+
ConnectionString = "couchbases://your-cluster-address",
91+
UserName = "username",
92+
Password = "password"
93+
};
94+
95+
return Cluster.ConnectAsync(clusterOptions).GetAwaiter().GetResult();
96+
});
97+
98+
kernelBuilder.Services.AddSingleton<IScope>(sp =>
99+
{
100+
var cluster = sp.GetRequiredService<ICluster>();
101+
var bucket = cluster.BucketAsync("bucket-name").GetAwaiter().GetResult();
102+
return bucket.Scope("scope-name");
103+
});
104+
105+
// Add Couchbase Vector Store
106+
kernelBuilder.Services.AddCouchbaseVectorStore();
107+
```
108+
109+
```csharp
110+
using Microsoft.Extensions.DependencyInjection;
111+
using Microsoft.SemanticKernel;
112+
using Couchbase.KeyValue;
113+
using Couchbase;
114+
115+
// Using IServiceCollection with ASP.NET Core.
116+
var builder = WebApplication.CreateBuilder(args);
117+
118+
builder.Services.AddSingleton<ICluster>(sp =>
119+
{
120+
var clusterOptions = new ClusterOptions
121+
{
122+
ConnectionString = "couchbases://your-cluster-address",
123+
UserName = "username",
124+
Password = "password"
125+
};
126+
127+
return Cluster.ConnectAsync(clusterOptions).GetAwaiter().GetResult();
128+
});
129+
130+
builder.Services.AddSingleton<IScope>(sp =>
131+
{
132+
var cluster = sp.GetRequiredService<ICluster>();
133+
var bucket = cluster.BucketAsync("bucket-name").GetAwaiter().GetResult();
134+
return bucket.Scope("scope-name");
135+
});
136+
137+
// Add Couchbase Vector Store
138+
builder.Services.AddCouchbaseVectorStore();
139+
```
140+
141+
You can construct a Couchbase Vector Store instance directly.
142+
143+
```csharp
144+
using Couchbase;
145+
using Couchbase.KeyValue;
146+
using Couchbase.SemanticKernel;
147+
148+
var clusterOptions = new ClusterOptions
149+
{
150+
ConnectionString = "couchbases://your-cluster-address",
151+
UserName = "username",
152+
Password = "password"
153+
};
154+
155+
var cluster = await Cluster.ConnectAsync(clusterOptions);
156+
157+
var bucket = await cluster.BucketAsync("bucket-name");
158+
var scope = bucket.Scope("scope-name");
159+
160+
var vectorStore = new CouchbaseVectorStore(scope);
161+
```
162+
163+
It is possible to construct a direct reference to a named collection.
164+
165+
```csharp
166+
using Couchbase;
167+
using Couchbase.KeyValue;
168+
using Couchbase.SemanticKernel;
169+
170+
var clusterOptions = new ClusterOptions
171+
{
172+
ConnectionString = "couchbases://your-cluster-address",
173+
UserName = "username",
174+
Password = "password"
175+
};
176+
177+
var cluster = await Cluster.ConnectAsync(clusterOptions);
178+
var bucket = await cluster.BucketAsync("bucket-name");
179+
var scope = bucket.Scope("scope-name");
180+
181+
var collection = new CouchbaseFtsVectorStoreRecordCollection<Hotel>(
182+
scope,
183+
"hotelCollection");
184+
```
185+
## Data mapping
186+
187+
The Couchbase connector uses `System.Text.Json.JsonSerializer` for data mapping. Properties in the data model are serialized into a JSON object and mapped to Couchbase storage.
188+
189+
Use the `JsonPropertyName` attribute to map a property to a different name in Couchbase storage. Alternatively, you can configure `JsonSerializerOptions` for advanced customization.
190+
```csharp
191+
using Couchbase.SemanticKernel;
192+
using Couchbase.KeyValue;
193+
using System.Text.Json;
194+
195+
var jsonSerializerOptions = new JsonSerializerOptions
196+
{
197+
PropertyNamingPolicy = JsonNamingPolicy.CamelCase
198+
};
199+
200+
var options = new CouchbaseFtsVectorStoreRecordCollectionOptions<Hotel>
201+
{
202+
JsonSerializerOptions = jsonSerializerOptions
203+
};
204+
205+
var collection = new CouchbaseFtsVectorStoreRecordCollection<Hotel>(scope, "hotels", options);
206+
```
207+
Using the above custom `JsonSerializerOptions` which is using `CamelCase`, the following data model will be mapped to the below json.
208+
209+
```csharp
210+
using System.Text.Json.Serialization;
211+
using Microsoft.Extensions.VectorData;
212+
213+
public class Hotel
214+
{
215+
[JsonPropertyName("hotelId")]
216+
[VectorStoreRecordKey]
217+
public string HotelId { get; set; }
218+
219+
[JsonPropertyName("hotelName")]
220+
[VectorStoreRecordData]
221+
public string HotelName { get; set; }
222+
223+
[JsonPropertyName("description")]
224+
[VectorStoreRecordData]
225+
public string Description { get; set; }
226+
227+
[JsonPropertyName("descriptionEmbedding")]
228+
[VectorStoreRecordVector(Dimensions: 4, DistanceFunction.DotProductSimilarity)]
229+
public ReadOnlyMemory<float> DescriptionEmbedding { get; set; }
230+
}
231+
```
232+
233+
```json
234+
{
235+
"hotelId": "h1",
236+
"hotelName": "Hotel Happy",
237+
"description": "A place where everyone can be happy",
238+
"descriptionEmbedding": [0.9, 0.1, 0.1, 0.1]
239+
}
240+
```
241+
242+
::: zone-end
243+
244+
::: zone pivot="programming-language-python"
245+
246+
## Not supported
247+
248+
Not supported.
249+
250+
::: zone-end
251+
::: zone pivot="programming-language-java"
252+
253+
## Not supported
254+
255+
Not supported.
256+
257+
::: zone-end

‎semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ Semantic Kernel provides a number of out-of-the-box Vector Store integrations ma
2727
| [Azure AI Search](./azure-ai-search-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
2828
| [Cosmos DB MongoDB (vCore)](./azure-cosmosdb-mongodb-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
2929
| [Cosmos DB No SQL](./azure-cosmosdb-nosql-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
30+
| [Couchbase](./couchbase-connector.md) | ✅ | ✅ | Couchbase |
3031
| [Elasticsearch](./elasticsearch-connector.md) | ✅ | ✅ | Elastic |
3132
| Chroma | Planned | | |
3233
| [In-Memory](./inmemory-connector.md) | ✅ | N/A | Microsoft Semantic Kernel Project |

0 commit comments

Comments
 (0)