Skip to content

Commit b2ec84a

Browse files
Minal-Agashe-Oraclealexkeh
Minal-Agashe-Oracle
and
alexkeh
authored
Oracledb java connector updates (#294)
* 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 --------- Co-authored-by: Alex Keh <alex.keh@oracle.com>
1 parent 5561411 commit b2ec84a

1 file changed

Lines changed: 134 additions & 8 deletions

File tree

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

Lines changed: 134 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -50,17 +50,29 @@ The Oracle Database Vector Store Connector can be used to access and manage data
5050
| StorageName supported? | Yes |
5151
| HybridSearch supported? | No |
5252

53-
5453
> [!IMPORTANT]
55-
> Vector data searches require Oracle Database 23ai. All other Oracle connector features are available using Oracle Database 19c or higher.
54+
> Vector data searches require Oracle Database 23ai or higher. All other Oracle connector features are available using Oracle Database 19c or higher.
5655
5756
::: zone-end
5857
::: zone pivot="programming-language-python"
5958
More information coming soon.
6059
::: zone-end
6160
::: zone pivot="programming-language-java"
6261

63-
More information coming soon.
62+
| Feature Area | Support |
63+
| ------------- |:-------------:|
64+
|Supported filter clauses|<ul><li>AnyTagEqualTo</li><li>EqualTo</li></ul>|
65+
|Collection maps to|SQL database table|
66+
|Supported key property types|<ul><li>short/Short</li><li>int/Integer</li><li>long/Long</li><li>String</li><li>UUID</li></ul>|
67+
|Supported data property types|<ul><li>byte/Byte</li><li>short/Short</li><li>int/Integer</li><li>long/Long</li><li>float/Float</li><li>double/Double</li><li>decimal/Decimal</li><li>DateTime</li><li>OffsetDataTime</li><li>Timestamp</li><li>String</li><li>UUID</li><li>List`<of all above types>`</li></ul>|
68+
|Supported vector property types|<ul><li>String</li><li>Collection`<Float>`</li><li>List`<Float>`</li><li>Float[]</li><li>float[]</li></ul>|
69+
|Supported index types|<ul><li>HNSW</li><li>IVF</li></ul>|
70+
|Supported distance functions|<ul><li>DOT_PRODUCT</li><li>COSINE_SIMILARITY</li><li>COSINE_DISTANCE</li><li>EUCLIDEAN_DISTANCE</li></ul>|
71+
|Supports multiple vectors in a record|Yes|
72+
|IsIndexed support?|Yes|
73+
|IsFullTextSearchable supported?| No|
74+
|StoragePropertyName supported?|No, use `@JsonProperty` instead|
75+
|HybridSearch supported?|No|
6476

6577
::: zone-end
6678

@@ -180,13 +192,77 @@ More information coming soon.
180192

181193
## Getting started
182194

183-
More information coming soon.
195+
Set up Oracle Database Vector Store connector.
196+
197+
```java
198+
// Copyright (c) Microsoft. All rights reserved.
199+
package com.microsoft.semantickernel.samples.syntaxexamples.memory;
200+
201+
import com.microsoft.semantickernel.data.jdbc.JDBCVectorStore;
202+
import com.microsoft.semantickernel.data.jdbc.JDBCVectorStoreOptions;
203+
import com.microsoft.semantickernel.data.jdbc.JDBCVectorStoreRecordCollection;
204+
import com.microsoft.semantickernel.data.jdbc.JDBCVectorStoreRecordCollectionOptions;
205+
import com.microsoft.semantickernel.data.jdbc.oracle.OracleVectorStoreQueryProvider;
206+
import com.microsoft.semantickernel.data.vectorstorage.VectorStoreRecordCollection;
207+
import com.microsoft.semantickernel.samples.documentationexamples.data.index.Hotel;
208+
import java.sql.SQLException;
209+
import java.util.Collections;
210+
import oracle.jdbc.datasource.impl.OracleDataSource;
211+
212+
public class VectorStoreWithOracle {
213+
214+
public static void main(String[] args) throws SQLException {
215+
System.out.println("==============================================================");
216+
System.out.println("============== Oracle Vector Store Example ===================");
217+
System.out.println("==============================================================");
218+
219+
// Configure the data source
220+
OracleDataSource dataSource = new OracleDataSource();
221+
dataSource.setURL("jdbc:oracle:thin:@localhost:1521/FREEPDB1");
222+
dataSource.setUser("scott");
223+
dataSource.setPassword("tiger");
224+
225+
// Build a query provider
226+
OracleVectorStoreQueryProvider queryProvider = OracleVectorStoreQueryProvider.builder()
227+
.withDataSource(dataSource)
228+
.build();
229+
230+
// Build a vector store
231+
JDBCVectorStore vectorStore = JDBCVectorStore.builder()
232+
.withDataSource(dataSource)
233+
.withOptions(JDBCVectorStoreOptions.builder()
234+
.withQueryProvider(queryProvider)
235+
.build())
236+
.build();
237+
238+
// Get a collection from the vector store
239+
VectorStoreRecordCollection<String, Hotel> collection = vectorStore.getCollection(
240+
"skhotels",
241+
JDBCVectorStoreRecordCollectionOptions.<Hotel>builder()
242+
.withRecordClass(Hotel.class)
243+
.build());
244+
245+
// Create the collection if it doesn't exist yet.
246+
collection.createCollectionAsync().block();
247+
248+
collection.upsertAsync(new Hotel("1",
249+
"HotelOne",
250+
"Desc for HotelOne",
251+
Collections.emptyList(), Collections.emptyList()),
252+
null)
253+
.block();
254+
255+
}
256+
257+
}
258+
```
259+
184260
::: zone-end
185261
::: zone pivot="programming-language-csharp"
186262

187263
## Data mapping
188264

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.
265+
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.
190266

191267
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.
192268

@@ -266,12 +342,62 @@ CREATE TABLE "MYSCHEMA"."Hotels"
266342
```
267343

268344
## Learn More
345+
269346
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)
347+
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)
349+
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)
271351
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
274352
- [Documentation: Oracle Data Provider for .NET](https://docs.oracle.com/en/database/oracle/oracle-database/23/odpnt/intro.html)
275353
Contains information on Oracle Data Provider for .NET (ODP.NET), the ADO.NET data provider for Oracle Database Vector Store connector.
276354

277355
::: zone-end
356+
::: zone pivot="programming-language-java"
357+
358+
## Data mapping
359+
360+
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.
361+
362+
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.
363+
364+
The following table shows the default primary key data type mapping between Oracle database and Java, along with the corresponding methods to retrieve data from a `ResultSet`:
365+
366+
| Java Type | Database Type | ResultSet Getter Method |
367+
| ------------- |:-------------:| -----:|
368+
| byte/Byte | NUMBER(3) | `resultSet.getByte(name)`|
369+
| short/Short | NUMBER(5) |`resultSet.getShort(name)`|
370+
|int/Integer | NUMBER(10) |`resultSet.getInt(name)`|
371+
|long/Long |NUMBER(19) |`resultSet.getLong(name)`|
372+
|String |NVARCHAR2(2000)|`resultSet.getString(name)`|
373+
|UUID |RAW(16) | `resultSet.getObject(name, java_type)`|
374+
375+
The following table shows the default data property type mapping along with the corresponding methods to retrieve data from a `ResultSet`:
376+
377+
| Java Type | Database Type | ResultSet Getter Method |
378+
| ------------- |:-------------:| -----:|
379+
| boolean | BOOLEAN | `resultSet.getByte(name)`|
380+
|byte/Byte |NUMBER(3)|`resultSet.getByte(name)`|
381+
|byte[] |RAW(2000)|`resultSet.getBytes(name)`|
382+
|short/Short |NUMBER(5)|`resultSet.getShort(name)`|
383+
|int/Integer |NUMBER(10)|`resultSet.getInt(name)`|
384+
|long/Long |NUMBER(19)|`resultSet.getLong(name)`|
385+
|float/Float |BINARY_FLOAT|`resultSet.getFloat(name)`|
386+
|double/Double|BINARY_DOUBLE|`resultSet.getDouble(name)`|
387+
|BigDecimal |NUMBER(18,2)|`resultSet.getBigDecimal(name)`|
388+
|OffsetDateTime|TIMESTAMP(7) WITH TIME ZONE|`resultSet.getTIMESTAMPTZ(name).offsetDateTimeValue()`|
389+
|String |CLOB/NVARCHAR2(%s)|`resultSet.getString(name)`|
390+
|UUID |RAW(16) |`resultSet.getObject(name, java_type)`|
391+
|List`<T>` |JSON |`resultSet.getObject(name, java_type)` Using `ojdbc-extensions-jackson-oson`|
392+
393+
Starting with Oracle Database 23ai, database vectors can be mapped to Java data types. Multiple vector columns are supported. The following table shows the default vector property type mapping:
394+
395+
| Java Type | Database Type
396+
| ------------- |:-------------:|
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) |
402+
403+
::: zone-end

0 commit comments

Comments
 (0)