Skip to content

Commit 5561411

Browse files
Minal-Agashe-OracleMinal-Agashe-Oracle
authored
Oracledb connector information (#289)
* Added oracle-db connector information. * Added oracledb-connector information. * Updated oracledb-connector for the correct documentation links * Updated oracle-connector with metadata information. * Updated file with the link to changed oracle-connector file. * Modied index.md file to remove C# oracle connector entry. * Updated TOC.yml for oracle database connector entry. * Updated oracle-connector .md file for ms author. * Updated oracle-connector.md for adding an important highlight. * Updated these two files based on the reviewer feedback. * Updated oracle-connector.md file for modifying custom mapping content. * As per the MS git validation warning added relative path of record definition in the oracle-connector md file.
1 parent 592d6ee commit 5561411

3 files changed

Lines changed: 282 additions & 0 deletions

File tree

‎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
@@ -20,6 +20,8 @@
2020
href: jdbc-connector.md
2121
- name: MongoDB connector
2222
href: mongodb-connector.md
23+
- name: Oracle Database connector
24+
href: oracle-connector.md
2325
- name: Pinecone connector
2426
href: pinecone-connector.md
2527
- name: Postgres connector

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ Semantic Kernel provides a number of out-of-the-box Vector Store integrations ma
4747
| Milvus | Planned | | |
4848
| [MongoDB](./mongodb-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
4949
| [Neon Serverless Postgres](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/neon1722366567200.neon_serverless_postgres_azure_prod) |Use [Postgres Connector](./postgres-connector.md)| ✅ | Microsoft Semantic Kernel Project |
50+
| [Oracle](./oracle-connector.md) | ✅ | ✅ | Oracle |
5051
| [Pinecone](./pinecone-connector.md) | ✅ | ❌ | Microsoft Semantic Kernel Project |
5152
| [Postgres](./postgres-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
5253
| [Qdrant](./qdrant-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
@@ -70,6 +71,7 @@ Semantic Kernel provides a number of out-of-the-box Vector Store integrations ma
7071
| [In-Memory](./inmemory-connector.md) | ✅ | N/A | Microsoft Semantic Kernel Project |
7172
| [MongoDB](./mongodb-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
7273
| [Neon Serverless Postgres](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/neon1722366567200.neon_serverless_postgres_azure_prod) |Use [Postgres Connector](./postgres-connector.md)| ✅ | Microsoft Semantic Kernel Project |
74+
| [Oracle](./oracle-connector.md) | Planned | | Oracle |
7375
| [Pinecone](./pinecone-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
7476
| [Postgres](./postgres-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
7577
| [Qdrant](./qdrant-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
@@ -87,6 +89,7 @@ Semantic Kernel provides a number of out-of-the-box Vector Store integrations ma
8789
| HSQLDB | Use [JDBC](./jdbc-connector.md) | ✅ | Microsoft Semantic Kernel Project |
8890
| [JDBC](./jdbc-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
8991
| MySQL | Use [JDBC](./jdbc-connector.md) | ✅ | Microsoft Semantic Kernel Project |
92+
| [Oracle](./oracle-connector.md) | ✅ | ✅ | Oracle |
9093
| Postgres | Use [JDBC](./jdbc-connector.md) | | Microsoft Semantic Kernel Project |
9194
| [Redis](./redis-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
9295
| SQLite | Use [JDBC](./jdbc-connector.md) | ✅ | Microsoft Semantic Kernel Project |

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

Lines changed: 277 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
---
2+
title: Using the Semantic Kernel Oracle Database Vector Store connector (Preview)
3+
description: Contains information on how to use a Semantic Kernel Vector store connector to access and manipulate data in Oracle Database.
4+
zone_pivot_groups: programming-languages
5+
author: minal-agashe-oracle
6+
ms.topic: conceptual
7+
ms.author: westey
8+
ms.date: 08/14/2025
9+
ms.service: semantic-kernel
10+
---
11+
# Using the Oracle Database Vector Store connector (Preview)
12+
13+
::: zone pivot="programming-language-csharp"
14+
15+
> [!WARNING]
16+
> The Oracle Database Vector Store functionality is in preview, and improvements that require breaking changes may still occur in limited circumstances before release.
17+
18+
::: zone-end
19+
::: zone pivot="programming-language-python"
20+
21+
> [!WARNING]
22+
> The Semantic Kernel Vector Store functionality is in preview, and improvements that require breaking changes may still occur in limited circumstances before release.
23+
24+
::: zone-end
25+
::: zone pivot="programming-language-java"
26+
27+
> [!WARNING]
28+
> The Semantic Kernel Vector Store functionality is in preview, and improvements that require breaking changes may still occur in limited circumstances before release.
29+
30+
::: zone-end
31+
32+
## Overview
33+
34+
The Oracle Database Vector Store Connector can be used to access and manage data in Oracle Database. The connector has the following characteristics.
35+
36+
::: zone pivot="programming-language-csharp"
37+
38+
| Feature Area | Support |
39+
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
40+
| Collection maps to | Oracle database table |
41+
| Supported key property types | <ul><li>short</li><li>int</li><li>long</li><li>string</li><li>Guid</li></ul> |
42+
| Supported data property types | <ul><li>bool</li><li>byte</li><li>short</li><li>int</li><li>decimal</li><li>long</li><li>float</li><li>double</li><li>DateTime</li><li>DateTimeOffset</li><li>TimeSpan</li><li>char</li><li>char[]</li><li>byte[]</li><li>String</li><li>Guid</li><li>*and nullable type of the above types*</i></li></ul> |
43+
| Supported vector property types | <ul><li>ReadOnlyMemory\<float\></li><li>Embedding\<float\></li><li>float[]</li><li>ReadOnlyMemory\<double\></li><li>Embedding\<double\></li><li>double[]</li><li>ReadOnlyMemory\<short\></li><li>Embedding\<short\></li><li>short[]</li><li>ReadOnlyMemory\<byte\></li><li>Embedding\<byte\></li><li>byte[]</li><li>BitArray</li><li>BinaryEmbedding</li></ul> |
44+
| Supported index types | <ul><li>Flat (default)</li><li>HNSW</li><li>IVF</li></ul> |
45+
| Supported distance functions | <ul><li>CosineDistance</li><ul><li>FLOAT32, FLOAT64, and INT8 vector default</li></ul><li>CosineSimilarity</li><li>DotProductSimilarity</li><li>NegativeDotProductSimilarity</li><li>EuclideanDistance</li><li>EuclideanSquaredDistance</li><li>HammingDistance</li><ul><li>BINARY vector default</li></ul><li>ManhattanDistance</li><li>JaccardSimilarity</li></ul> |
46+
| Supported filter clauses | <ul><li>==</li><li>!=</li><li><</li><li><=</li><li>></li><li>>=</li><li>List.Contains() <ul><li>Only when checking if the model property is in the list</li></ul></li></ul> |
47+
| Supports zero, one, or multiple vectors in a record | Yes |
48+
| IsIndexed supported? | Yes |
49+
| IsFullTextSearchable supported? | No |
50+
| StorageName supported? | Yes |
51+
| HybridSearch supported? | No |
52+
53+
54+
> [!IMPORTANT]
55+
> Vector data searches require Oracle Database 23ai. All other Oracle connector features are available using Oracle Database 19c or higher.
56+
57+
::: zone-end
58+
::: zone pivot="programming-language-python"
59+
More information coming soon.
60+
::: zone-end
61+
::: zone pivot="programming-language-java"
62+
63+
More information coming soon.
64+
65+
::: zone-end
66+
67+
::: zone pivot="programming-language-csharp"
68+
69+
## Getting started
70+
71+
Add the Oracle Database Vector Store connector NuGet package to your project.
72+
73+
```dotnetcli
74+
dotnet add package Oracle.VectorData --prerelease
75+
```
76+
77+
You can add the vector store to the `IServiceCollection` dependency injection container using extension methods provided by Semantic Kernel. In this case, an instance of the `Oracle.VectorData.OracleVectorStore` class also gets registered with the container.
78+
79+
```csharp
80+
using Microsoft.SemanticKernel;
81+
using Oracle.VectorData;
82+
using Microsoft.Extensions.DependencyInjection;
83+
84+
// Using Kernel Builder.
85+
var builder = Kernel.CreateBuilder();
86+
builder.Services.AddOracleVectorStore("<connection string>");
87+
```
88+
89+
```csharp
90+
using Microsoft.AspNetCore.Builder;
91+
using Oracle.VectorData;
92+
using Microsoft.Extensions.DependencyInjection;
93+
94+
// Using IServiceCollection with ASP.NET Core.
95+
var builder = WebApplication.CreateBuilder(args);
96+
builder.Services.AddOracleVectorStore("<connection string>");
97+
```
98+
99+
Extension methods that take no parameters are also available. These require an instance of the `Oracle.ManagedDataAccess.Client.OracleDataSource` class to be separately registered with the dependency injection container.
100+
101+
```csharp
102+
using Microsoft.SemanticKernel;
103+
using Oracle.VectorData;
104+
using Microsoft.Extensions.DependencyInjection;
105+
using Oracle.ManagedDataAccess.Client;
106+
107+
// Using Kernel Builder.
108+
var kernelBuilder = Kernel.CreateBuilder();
109+
builder.Services.AddSingleton<OracleDataSource>(sp =>
110+
{
111+
OracleDataSourceBuilder dataSourceBuilder = new("<connection string>");
112+
return dataSourceBuilder.Build();
113+
});
114+
115+
builder.Services.AddOracleVectorStore();
116+
```
117+
118+
```csharp
119+
using Microsoft.AspNetCore.Builder;
120+
using Oracle.VectorData;
121+
using Microsoft.Extensions.DependencyInjection;
122+
using Oracle.ManagedDataAccess.Client;
123+
124+
// Using IServiceCollection with ASP.NET Core.
125+
var builder = WebApplication.CreateBuilder(args);
126+
builder.Services.AddSingleton<OracleDataSource>(sp =>
127+
{
128+
OracleDataSourceBuilder dataSourceBuilder = new("<connection string>");
129+
return dataSourceBuilder.Build();
130+
});
131+
132+
builder.Services.AddOracleVectorStore();
133+
```
134+
135+
You can construct an Oracle Database Vector Store instance directly with a custom data source or with a connection string.
136+
137+
```csharp
138+
using Oracle.VectorData;
139+
using Oracle.ManagedDataAccess.Client;
140+
141+
OracleDataSourceBuilder dataSourceBuilder = new("<connection string>");
142+
var dataSource = dataSourceBuilder.Build();
143+
144+
var connection = new OracleVectorStore(dataSource);
145+
```
146+
147+
```csharp
148+
using Oracle.VectorData;
149+
150+
var connection = new OracleVectorStore("<connection string>");
151+
```
152+
153+
It is possible to construct a direct reference to a named collection with a custom data source or with a connection string.
154+
155+
```csharp
156+
using Oracle.VectorData;
157+
using Oracle.ManagedDataAccess.Client;
158+
159+
OracleDataSourceBuilder dataSourceBuilder = new("<connection string>");
160+
var dataSource = dataSourceBuilder.Build();
161+
162+
var collection = new OracleCollection<string, Hotel>(dataSource, "skhotels");
163+
```
164+
165+
```csharp
166+
using Oracle.VectorData;
167+
168+
var collection = new OracleCollection<string, Hotel>("<connection string>", "skhotels");
169+
```
170+
171+
::: zone-end
172+
173+
::: zone pivot="programming-language-python"
174+
175+
## Getting started
176+
177+
More information coming soon.
178+
::: zone-end
179+
::: zone pivot="programming-language-java"
180+
181+
## Getting started
182+
183+
More information coming soon.
184+
::: zone-end
185+
::: zone pivot="programming-language-csharp"
186+
187+
## Data mapping
188+
189+
The Oracle Database Vector Store connector provides a default mapper when mapping data from the data model to storage. This mapper does a direct conversion of the data model properties list to the Oracle database columns to convert to the storage schema.
190+
191+
The Oracle Database Vector Store connector supports data model annotations and record definitions.Using annotations, the information can be provided to the data model for creating indexes and database column mapping. Using [record definitions](../schema-with-record-definition.md), the information can be defined and supplied separately from the data model.
192+
193+
The following table shows the default primary key data type mapping between Oracle database and C#:
194+
195+
| C# Data Type | Database Type |
196+
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
197+
| short/int16 | NUMBER(5) |
198+
| int/int32 | NUMBER(10) |
199+
| long/int64 | NUMBER(19) |
200+
| string | NVARCHAR2(2000) |
201+
| Guid | RAW(16) |
202+
203+
The following table shows the default data property type mapping, including nullable types:
204+
205+
| C# Data Type | Database Type |
206+
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
207+
| bool | BOOLEAN for Oracle Database 23ai and higher <br> NUMBER(1) for earlier versions |
208+
| byte | NUMBER(3) |
209+
| short/int16 | NUMBER(5) |
210+
| int/int32 | NUMBER(10) |
211+
| decimal | NUMBER(18,2) |
212+
| long/int64 | NUMBER(19) |
213+
| float | BINARY_FLOAT |
214+
| double | BINARY_DOUBLE |
215+
| DateTime | TIMESTAMP(7) |
216+
| DateTimeOffset | TIMESTAMP(7) WITH TIME ZONE |
217+
| TimeSpan | INTERVAL DAY(8) TO SECOND(7) |
218+
| char | NVARCHAR2(1) |
219+
| char[] | NVARCHAR2(2000) |
220+
| byte[] | RAW(2000) |
221+
| string | NVARCHAR2(2000) |
222+
| Guid | RAW(16) |
223+
224+
Starting with Oracle Database 23ai, database vectors can be mapped to .NET. data types. Multiple vector columns are supported. The following table shows the default vector property type mapping, including nullable types:
225+
226+
| C# Data Type | Database Type |
227+
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
228+
| <ul><li>ReadOnlyMemory\<byte></li><li>Embedding\<System.Byte></li> <li>BinaryEmbedding</li><li>Embedding\<byte></li><li>byte[]</li><li>System.Byte[]</li><li>BitArray</li></ul> | VECTOR(dimensions, BINARY) |
229+
| <ul><li>ReadOnlyMemory\<short></li><li>ReadOnlyMemory\<System.Int16></li><li>Embedding\<short></li><li>Embedding\<System.Int16></li><li>short[]</li><li>System.Int16[]</li></ul> | VECTOR(dimensions, INT8) |
230+
| <ul><li>ReadOnlyMemory\<double></li><li>ReadOnlyMemory\<System.Double></li><li>Embedding\<System.Double></li><li>Embedding\<double></li><li>double[]</li><li>System.Double[]</li></ul> | VECTOR(dimensions, FLOAT64) |
231+
| <ul><li>ReadOnlyMemory\<float></li><li>ReadOnlyMemory\<System.Float></li><li>Embedding\<float></li><li>Embedding\<System.Float></li><li>float[]</li><li>System.Float[]</li></ul> | VECTOR(dimensions, FLOAT32) |
232+
233+
### Property name override
234+
235+
For data properties and vector properties, you can override names to use in storage that are different from the data model property names. The property name override occurs when setting the `StorageName` option either in the data model properties or record definition.
236+
237+
Here is a data model with `StorageName` set code sample and how that will be represented in an Oracle SQL command.
238+
239+
```csharp
240+
using Microsoft.Extensions.VectorData;
241+
242+
public class Hotel
243+
{
244+
[VectorStoreKey]
245+
public long HotelId { get; set; }
246+
247+
[VectorStoreData(StorageName = "hotel_name")]
248+
public string? HotelName { get; set; }
249+
250+
[VectorStoreData(StorageName = "hotel_description")]
251+
public string? Description { get; set; }
252+
253+
[VectorStoreVector(Dimensions: 384, DistanceFunction = DistanceFunction.CosineDistance)]
254+
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
255+
}
256+
```
257+
258+
```SQL
259+
CREATE TABLE "MYSCHEMA"."Hotels"
260+
("HotelId" NUMBER(10),
261+
"hotel_name" NVARCHAR2(2000),
262+
"hotel_description" NVARCHAR2(2000),
263+
"DescriptionEmbedding" VECTOR(384, FLOAT32),
264+
PRIMARY KEY ( "HotelId" )
265+
);
266+
```
267+
268+
## Learn More
269+
Refer to the following Oracle Database Vector Store connector resources to learn more:
270+
- [Documentation: Oracle Database Vector Store Connector Classes for Semantic Kernel (.NET) APIs](https://docs.oracle.com/en/database/oracle/oracle-database/23/odpnt/oracle-database-vector-store-connector-semantic-kernel-classes.html)
271+
Contains information on Oracle Database Vector Store connector classes for adding data, retrieving data, and performing vector search in the Oracle vector database.
272+
- Sample Code: Oracle Database Vector Store Connector for Semantic Kernel (.NET)
273+
- Coming soon
274+
- [Documentation: Oracle Data Provider for .NET](https://docs.oracle.com/en/database/oracle/oracle-database/23/odpnt/intro.html)
275+
Contains information on Oracle Data Provider for .NET (ODP.NET), the ADO.NET data provider for Oracle Database Vector Store connector.
276+
277+
::: zone-end

0 commit comments

Comments
 (0)