Skip to content

Commit 7ff289a

Browse files
priyankanair8Minal-Agashe-Oraclealexkeh
authored
Oracledb Connector Updates for Python (#331)
* 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. * Updated oracle-connector file for Oracle Java connector information. * Updated oracle connector page for Java connector information. * Fixed typo * updated oracle connector page to fix the validation errors. * Fixed validation errors in oracle connector page. * Update oracle-connector.md * Update .NET info in oracle-connector.md * Update oracle-connector.md for formatting Java support table. * Updated oracle connector page for additinal information on using Jaccard similarity in C# connector. Also, updated the table formatting for Java connector. * Change single quotes to double quotes Changed single quotes to double quotes to ensure correct C# syntax is used, * Updated Oracledb Connector for Python * Change ms.topic to article based on suggestion * Address review comment * Remove extra install step --------- Co-authored-by: Minal Agashe <minal.n.agashe@oracle.com> Co-authored-by: Alex Keh <alex.keh@oracle.com>
1 parent f0be4d3 commit 7ff289a

File tree

2 files changed

+133
-32
lines changed

2 files changed

+133
-32
lines changed

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Out-of-the-box Vector Store connectors (Preview)
33
description: Out-of-the-box Vector Store connectors
44
zone_pivot_groups: programming-languages
55
author: westey-m
6-
ms.topic: conceptual
6+
ms.topic: article
77
ms.author: westey
88
ms.date: 07/08/2024
99
ms.service: semantic-kernel
@@ -71,7 +71,7 @@ Semantic Kernel provides a number of out-of-the-box Vector Store integrations ma
7171
| [In-Memory](./inmemory-connector.md) | ✅ | N/A | Microsoft Semantic Kernel Project |
7272
| [MongoDB](./mongodb-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
7373
| [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 |
74+
| [Oracle](./oracle-connector.md) | ✅ | ✅ | Oracle |
7575
| [Pinecone](./pinecone-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
7676
| [Postgres](./postgres-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |
7777
| [Qdrant](./qdrant-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project |

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

Lines changed: 131 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Using the Semantic Kernel Oracle Database Vector Store connector (Preview
33
description: Contains information on how to use a Semantic Kernel Vector store connector to access and manipulate data in Oracle Database.
44
zone_pivot_groups: programming-languages
55
author: minal-agashe-oracle
6-
ms.topic: conceptual
6+
ms.topic: article
77
ms.author: westey
88
ms.date: 08/14/2025
99
ms.service: semantic-kernel
@@ -55,7 +55,25 @@ The Oracle Database Vector Store Connector can be used to access and manage data
5555
5656
::: zone-end
5757
::: zone pivot="programming-language-python"
58-
More information coming soon.
58+
59+
Feature Area | Support |
60+
|---------------|----------|
61+
| Collection maps to | An Oracle Database table |
62+
| Supported key property types | <ul><li>str</li><li>int</li><li>uuid.UUID</li></ul> |
63+
| Supported data property types | <ul><li>str</li><li>int</li><li>long</li><li>float</li><li>bool</li><li>decimal</li><li>byte</li><li>bytes</li><li>uuid.UUID</li><li>datetime.date</li><li>datetime.datetime</li><li>datetime.timedelta</li><li>list[str]</li><li>dict[str, Any]</li><li>list[dict[str, Any]]</li></ul> |
64+
| Supported vector property types | <ul><li>list[float]</li><li>numpy array</li></ul> |
65+
| Supported index types | <ul><li>HNSW</li><li>IVF</li></ul> |
66+
| Supported distance functions | <ul><li>COSINE_DISTANCE</li><li>EUCLIDEAN_DISTANCE</li><li>EUCLIDEAN_SQUARED_DISTANCE</li><li>DOT_PROD</li><li>HAMMING</li><li>MANHATTAN</li><li>DEFAULT</li></ul> |
67+
| Supported filter clauses | Python lambdas with comparisons, boolean operators, string methods (startswith, endswith), between, and datetime, translated to SQL with bind variables |
68+
| IsIndexed supported? | Yes |
69+
| IsFullTextSearchable supported? | No |
70+
| StoragePropertyName supported? | Yes |
71+
| HybridSearch supported? | No |
72+
73+
> [!IMPORTANT]
74+
> Vector data searches require Oracle Database 23ai or later. All other Oracle connector features are available using Oracle Database 19c or later.
75+
> Also, python-oracledb 3.3 or later is required.
76+
5977
::: zone-end
6078
::: zone pivot="programming-language-java"
6179

@@ -92,7 +110,7 @@ You can add the vector store to the `IServiceCollection` dependency injection co
92110
using Microsoft.SemanticKernel;
93111
using Oracle.VectorData;
94112
using Microsoft.Extensions.DependencyInjection;
95-
113+
96114
// Using Kernel Builder.
97115
var builder = Kernel.CreateBuilder();
98116
builder.Services.AddOracleVectorStore("<connection string>");
@@ -102,7 +120,7 @@ builder.Services.AddOracleVectorStore("<connection string>");
102120
using Microsoft.AspNetCore.Builder;
103121
using Oracle.VectorData;
104122
using Microsoft.Extensions.DependencyInjection;
105-
123+
106124
// Using IServiceCollection with ASP.NET Core.
107125
var builder = WebApplication.CreateBuilder(args);
108126
builder.Services.AddOracleVectorStore("<connection string>");
@@ -115,15 +133,15 @@ using Microsoft.SemanticKernel;
115133
using Oracle.VectorData;
116134
using Microsoft.Extensions.DependencyInjection;
117135
using Oracle.ManagedDataAccess.Client;
118-
136+
119137
// Using Kernel Builder.
120138
var kernelBuilder = Kernel.CreateBuilder();
121139
builder.Services.AddSingleton<OracleDataSource>(sp =>
122140
{
123-
OracleDataSourceBuilder dataSourceBuilder = new("<connection string>");
141+
OracleDataSourceBuilder dataSourceBuilder = new("<connection string>");
124142
return dataSourceBuilder.Build();
125143
});
126-
144+
127145
builder.Services.AddOracleVectorStore();
128146
```
129147

@@ -132,15 +150,15 @@ using Microsoft.AspNetCore.Builder;
132150
using Oracle.VectorData;
133151
using Microsoft.Extensions.DependencyInjection;
134152
using Oracle.ManagedDataAccess.Client;
135-
153+
136154
// Using IServiceCollection with ASP.NET Core.
137155
var builder = WebApplication.CreateBuilder(args);
138156
builder.Services.AddSingleton<OracleDataSource>(sp =>
139157
{
140-
OracleDataSourceBuilder dataSourceBuilder = new("<connection string>");
158+
OracleDataSourceBuilder dataSourceBuilder = new("<connection string>");
141159
return dataSourceBuilder.Build();
142160
});
143-
161+
144162
builder.Services.AddOracleVectorStore();
145163
```
146164

@@ -149,16 +167,16 @@ You can construct an Oracle Database Vector Store instance directly with a custo
149167
```csharp
150168
using Oracle.VectorData;
151169
using Oracle.ManagedDataAccess.Client;
152-
170+
153171
OracleDataSourceBuilder dataSourceBuilder = new("<connection string>");
154172
var dataSource = dataSourceBuilder.Build();
155-
173+
156174
var connection = new OracleVectorStore(dataSource);
157175
```
158176

159177
```csharp
160178
using Oracle.VectorData;
161-
179+
162180
var connection = new OracleVectorStore("<connection string>");
163181
```
164182

@@ -167,16 +185,16 @@ It is possible to construct a direct reference to a named collection with a cust
167185
```csharp
168186
using Oracle.VectorData;
169187
using Oracle.ManagedDataAccess.Client;
170-
188+
171189
OracleDataSourceBuilder dataSourceBuilder = new("<connection string>");
172190
var dataSource = dataSourceBuilder.Build();
173-
191+
174192
var collection = new OracleCollection<string, Hotel>(dataSource, "skhotels");
175193
```
176194

177195
```csharp
178196
using Oracle.VectorData;
179-
197+
180198
var collection = new OracleCollection<string, Hotel>("<connection string>", "skhotels");
181199
```
182200

@@ -186,7 +204,44 @@ var collection = new OracleCollection<string, Hotel>("<connection string>", "skh
186204

187205
## Getting started
188206

189-
More information coming soon.
207+
Install the Oracle Database Vector Store connector:
208+
209+
```cli
210+
pip install semantic-kernel[oracledb]
211+
```
212+
213+
Import the OracleSettings, OracleStore, and OracleCollection classes.
214+
215+
```python
216+
from semantic_kernel.connectors.oracle import OracleSettings, OracleStore, OracleCollection
217+
```
218+
219+
The OracleSettings class holds the configuration required to create an asynchronous connection to Oracle Database. The OracleStore class is used to store and retrieve data, while the OracleCollection class manages and searches records within a collection. Use these classes to set up the Oracle Vector Store.
220+
221+
```python
222+
# Read the environment settings
223+
oracle_settings = OracleSettings()
224+
225+
# Create a connection pool
226+
pool = await oracle_settings.create_connection_pool(
227+
wallet_location=<wallet_location>,
228+
wallet_password=<wallet_password>)
229+
230+
# Create an Oracle Vector Store
231+
store = OracleStore(
232+
connection_pool=pool,
233+
)
234+
235+
# Get a collection
236+
collection = await store.get_collection(
237+
record_type=HotelSample,
238+
collection_name=Hotel,
239+
embedding_generator=text_embedding)
240+
241+
# Create a collection if it does not exist
242+
await collection.ensure_collection_exists()
243+
```
244+
190245
::: zone-end
191246
::: zone pivot="programming-language-java"
192247

@@ -314,18 +369,18 @@ Here is a data model with `StorageName` set code sample and how that will be rep
314369

315370
```csharp
316371
using Microsoft.Extensions.VectorData;
317-
372+
318373
public class Hotel
319374
{
320375
[VectorStoreKey]
321376
public long HotelId { get; set; }
322-
377+
323378
[VectorStoreData(StorageName = "hotel_name")]
324379
public string? HotelName { get; set; }
325-
380+
326381
[VectorStoreData(StorageName = "hotel_description")]
327382
public string? Description { get; set; }
328-
383+
329384
[VectorStoreVector(Dimensions: 384, DistanceFunction = DistanceFunction.CosineDistance)]
330385
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
331386
}
@@ -345,13 +400,59 @@ CREATE TABLE "MYSCHEMA"."Hotels"
345400

346401
Refer to the following Oracle Database Vector Store connector resources to learn more:
347402

348-
- [Introducing the Oracle Database Vector Store Connector for Semantic Kernel](https://medium.com/oracledevs/announcing-the-oracle-database-vector-store-connector-for-semantic-kernel-adb83e806d4e)
403+
- [Introducing the Oracle Database Vector Store Connector for Semantic Kernel](https://medium.com/oracledevs/announcing-the-oracle-database-vector-store-connector-for-semantic-kernel-adb83e806d4e)
349404
Describes key connector features, classes, and guides the reader through a sample AI vector search application using the connector.
350-
- [Documentation: Oracle Database Vector Store Connector Classes for Semantic Kernel (.NET) APIs](https://docs.oracle.com/en/database/oracle/oracle-database/23/odpnt/VSConnector4SKClasses.html)
351-
Contains information on Oracle Database Vector Store connector classes for adding data, retrieving data, and performing vector search in the Oracle vector database.
352-
- [Documentation: Oracle Data Provider for .NET](https://docs.oracle.com/en/database/oracle/oracle-database/23/odpnt/intro.html)
405+
- [Documentation: Oracle Database Vector Store Connector Classes for Semantic Kernel (.NET) APIs](https://docs.oracle.com/en/database/oracle/oracle-database/23/odpnt/VSConnector4SKClasses.html)
406+
Contains information on Oracle Database Vector Store connector classes for adding data, retrieving data, and performing vector search in the Oracle vector database.
407+
- [Documentation: Oracle Data Provider for .NET](https://docs.oracle.com/en/database/oracle/oracle-database/23/odpnt/intro.html)
353408
Contains information on Oracle Data Provider for .NET (ODP.NET), the ADO.NET data provider for Oracle Database Vector Store connector.
354409

410+
::: zone-end
411+
::: zone pivot="programming-language-python"
412+
413+
## Data Mapping
414+
415+
The Oracle Database Vector Store connector provides a default mapper when mapping from the data model to storage. This mapper does a direct conversion of the list of properties on the data model to the Oracle Database columns to convert to the storage schema.
416+
417+
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.
418+
419+
The following table shows the default primary key data type mapping between Oracle Database and Python:
420+
421+
| Python Type | Oracle SQL Type |
422+
|---------------------------|-----------------|
423+
| str | VARCHAR(n), Using str(n) in the type option sets the Oracle VARCHAR length to n. If n is not specified, the default length is 4000. |
424+
| int | NUMBER(10) |
425+
| byte | NUMBER(3) |
426+
| long | NUMBER(19) |
427+
| decimal | NUMBER |
428+
| float | BINARY_FLOAT |
429+
| double | BINARY_DOUBLE |
430+
| bool | BOOLEAN |
431+
| UUID | RAW(16) |
432+
| date | DATE |
433+
| datetime.datetime | TIMESTAMP |
434+
| datetime.timedelta | INTERVAL DAY TO SECOND |
435+
| clob | CLOB, can be specified explicitly, not a native Python type |
436+
| blob | BLOB, can be specified explicitly, not a native Python type |
437+
| list[str], dict[str, Any] | JSON |
438+
| list[dict[str, Any]] | JSON |
439+
| bytes | RAW(2000) |
440+
441+
Starting with Oracle Database 23ai, database vectors can be mapped to Python data types. Multiple vector columns are supported. The following table shows the default vector property type mapping:
442+
443+
| Python Type | Database Type |
444+
|-------------|----------------|
445+
| uint8 | BINARY |
446+
| int8 | INT8 |
447+
| float | FLOAT64 |
448+
| float32 | FLOAT32 |
449+
| float64 | FLOAT64 |
450+
| binary | BINARY |
451+
452+
## Learn More
453+
Refer to the following resources to learn more:
454+
- [Documentation: python-oracledb](https://python-oracledb.readthedocs.io/en/latest/index.html)
455+
355456
::: zone-end
356457
::: zone pivot="programming-language-java"
357458

@@ -394,10 +495,10 @@ The following table shows the default data property type mapping along with the
394495

395496
| Java Type | Database Type|
396497
| ------------- |-------------|
397-
| String | VECTOR(%d, FLOAT32) |
398-
|Collection`<Float>`|VECTOR(%d, FLOAT32) |
399-
|List`<Float>` |VECTOR(%d, FLOAT32) |
400-
|Float[] |VECTOR(%d, FLOAT32) |
401-
|float[] |VECTOR(%d, FLOAT32) |
498+
| String | VECTOR(%d, FLOAT32) |
499+
|Collection`<Float>`|VECTOR(%d, FLOAT32) |
500+
|List`<Float>` |VECTOR(%d, FLOAT32) |
501+
|Float[] |VECTOR(%d, FLOAT32) |
502+
|float[] |VECTOR(%d, FLOAT32) |
402503

403504
::: zone-end

0 commit comments

Comments
 (0)