diff --git a/manual/core/README.md b/manual/core/README.md index 8cc6b670b99..349a810f3aa 100644 --- a/manual/core/README.md +++ b/manual/core/README.md @@ -231,34 +231,35 @@ See [AccessibleByName] for an explanation of the conversion rules. ##### CQL to Java type mapping -| CQL3 data type | Getter name | Java type | See also | -|---------------------|----------------|----------------------|-------------------------------------| -| ascii | getString | java.lang.String | | -| bigint | getLong | long | | -| blob | getByteBuffer | java.nio.ByteBuffer | | -| boolean | getBoolean | boolean | | -| counter | getLong | long | | -| date | getLocalDate | java.time.LocalDate | [Temporal types](temporal_types/) | -| decimal | getBigDecimal | java.math.BigDecimal | | -| double | getDouble | double | | -| duration | getCqlDuration | [CqlDuration] | [Temporal types](temporal_types/) | -| float | getFloat | float | | -| inet | getInetAddress | java.net.InetAddress | | -| int | getInt | int | | -| list | getList | java.util.List | | -| map | getMap | java.util.Map | | -| set | getSet | java.util.Set | | -| smallint | getShort | short | | -| text | getString | java.lang.String | | -| time | getLocalTime | java.time.LocalTime | [Temporal types](temporal_types/) | -| timestamp | getInstant | java.time.Instant | [Temporal types](temporal_types/) | -| timeuuid | getUuid | java.util.UUID | | -| tinyint | getByte | byte | | -| tuple | getTupleValue | [TupleValue] | [Tuples](tuples/) | -| user-defined types | getUDTValue | [UDTValue] | [User-defined types](udts/) | -| uuid | getUuid | java.util.UUID | | -| varchar | getString | java.lang.String | | -| varint | getBigInteger | java.math.BigInteger | | +| CQL3 data type | Getter name | Java type | See also | +|--------------------|----------------|----------------------|-----------------------------------| +| ascii | getString | java.lang.String | | +| bigint | getLong | long | | +| blob | getByteBuffer | java.nio.ByteBuffer | | +| boolean | getBoolean | boolean | | +| counter | getLong | long | | +| date | getLocalDate | java.time.LocalDate | [Temporal types](temporal_types/) | +| decimal | getBigDecimal | java.math.BigDecimal | | +| double | getDouble | double | | +| duration | getCqlDuration | [CqlDuration] | [Temporal types](temporal_types/) | +| float | getFloat | float | | +| inet | getInetAddress | java.net.InetAddress | | +| int | getInt | int | | +| list | getList | java.util.List | | +| map | getMap | java.util.Map | | +| set | getSet | java.util.Set | | +| smallint | getShort | short | | +| text | getString | java.lang.String | | +| time | getLocalTime | java.time.LocalTime | [Temporal types](temporal_types/) | +| timestamp | getInstant | java.time.Instant | [Temporal types](temporal_types/) | +| timeuuid | getUuid | java.util.UUID | | +| tinyint | getByte | byte | | +| tuple | getTupleValue | [TupleValue] | [Tuples](tuples/) | +| user-defined types | getUDTValue | [UDTValue] | [User-defined types](udts/) | +| uuid | getUuid | java.util.UUID | | +| varchar | getString | java.lang.String | | +| varint | getBigInteger | java.math.BigInteger | | +| vector | getVector | [CqlVector] | [Custom Codecs](custom_codecs/) | Sometimes the driver has to infer a CQL type from a Java type (for example when handling the values of [simple statements](statements/simple/)); for those that have multiple CQL equivalents, it makes @@ -322,6 +323,7 @@ for (ColumnDefinitions.Definition definition : row.getColumnDefinitions()) { [AccessibleByName]: https://docs.datastax.com/en/drivers/java/4.14/com/datastax/oss/driver/api/core/data/AccessibleByName.html [GenericType]: https://docs.datastax.com/en/drivers/java/4.14/com/datastax/oss/driver/api/core/type/reflect/GenericType.html [CqlDuration]: https://docs.datastax.com/en/drivers/java/4.14/com/datastax/oss/driver/api/core/data/CqlDuration.html +[CqlVector]: https://docs.datastax.com/en/drivers/java/4.14/com/datastax/oss/driver/api/core/data/CqlVector.html [TupleValue]: https://docs.datastax.com/en/drivers/java/4.14/com/datastax/oss/driver/api/core/data/TupleValue.html [UdtValue]: https://docs.datastax.com/en/drivers/java/4.14/com/datastax/oss/driver/api/core/data/UdtValue.html [SessionBuilder.addContactPoint()]: https://docs.datastax.com/en/drivers/java/4.14/com/datastax/oss/driver/api/core/session/SessionBuilder.html#addContactPoint-java.net.InetSocketAddress- diff --git a/manual/core/custom_codecs/README.md b/manual/core/custom_codecs/README.md index 92a0274577b..ae873d0b60d 100644 --- a/manual/core/custom_codecs/README.md +++ b/manual/core/custom_codecs/README.md @@ -256,6 +256,17 @@ that maps instances of that class to Json strings, using a newly-allocated, defa It is also possible to pass a custom `ObjectMapper` instance using [ExtraTypeCodecs.json(Class, ObjectMapper)] instead. +#### Mapping CQL vectors to Java array + +By default, the driver maps CQL `vector` to the [CqlVector] value type. If you prefer to deal with +arrays, the driver offers the following codec: + +| Codec | CQL type | Java type | +|-------------------------------------------|-----------------|-----------| +| [ExtraTypeCodecs.floatVectorToArray(int)] | `vector` | `float[]` | + +This release only provides a codec for vectors containing float values. + ### Writing codecs If none of the driver built-in codecs above suits you, it is also possible to roll your own. @@ -707,6 +718,7 @@ private static String formatRow(Row row) { [ExtraTypeCodecs.enumOrdinalsOf(Class)]: https://docs.datastax.com/en/drivers/java/4.14/com/datastax/oss/driver/api/core/type/codec/ExtraTypeCodecs.html#enumOrdinalsOf-java.lang.Class- [ExtraTypeCodecs.json(Class)]: https://docs.datastax.com/en/drivers/java/4.14/com/datastax/oss/driver/api/core/type/codec/ExtraTypeCodecs.html#json-java.lang.Class- [ExtraTypeCodecs.json(Class, ObjectMapper)]: https://docs.datastax.com/en/drivers/java/4.14/com/datastax/oss/driver/api/core/type/codec/ExtraTypeCodecs.html#json-java.lang.Class-com.fasterxml.jackson.databind.ObjectMapper- +[ExtraTypeCodecs.floatVectorToArray(int)]: https://docs.datastax.com/en/drivers/java/4.14/com/datastax/oss/driver/api/core/type/codec/ExtraTypeCodecs.html#floatVectorToArray-int- [TypeCodecs.BLOB]: https://docs.datastax.com/en/drivers/java/4.14/com/datastax/oss/driver/api/core/type/codec/TypeCodecs.html#BLOB [TypeCodecs.TIMESTAMP]: https://docs.datastax.com/en/drivers/java/4.14/com/datastax/oss/driver/api/core/type/codec/TypeCodecs.html#TIMESTAMP diff --git a/upgrade_guide/README.md b/upgrade_guide/README.md index 785f51290da..6310f220c3d 100644 --- a/upgrade_guide/README.md +++ b/upgrade_guide/README.md @@ -1,5 +1,60 @@ ## Upgrade guide +### 4.17.0 + +#### Beta support for Java17 + +With the completion of [JAVA-3042](https://datastax-oss.atlassian.net/browse/JAVA-3042) the driver now passes our automated test matrix for Java driver releases. +While all features function normally when run with Java 17 tests, we do not offer full support for this +platform until we've received feedback from other users in the ecosystem. + +If you discover an issue with the Java driver running on Java 17, please let us know. We will triage and address Java 17 issues. + +#### Updated API for vector search + +The 4.16.0 release introduced support for the CQL `vector` datatype. This release modifies the `CqlVector` +value type used to represent a CQL vector to make it easier to use. `CqlVector` now implements the Iterable interface +as well as several methods modelled on the JDK's List interface. For more, see +[JAVA-3060](https://datastax-oss.atlassian.net/browse/JAVA-3060). + +The builder interface was replaced with factory methods that resemble similar methods on `CqlDuration`. +For example, the following code will create a keyspace and table, populate that table with some data, and then execute +a query that will return a `vector` type. This data is retrieved directly via `Row.getVector()` and the resulting +`CqlVector` value object can be interrogated directly. + +```java +try (CqlSession session = new CqlSessionBuilder().withLocalDatacenter("datacenter1").build()) { + + session.execute("DROP KEYSPACE IF EXISTS test"); + session.execute("CREATE KEYSPACE test WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1}"); + session.execute("CREATE TABLE test.foo(i int primary key, j vector)"); + session.execute("CREAT CUSTOM INDEX ann_index ON test.foo(j) USING 'StorageAttachedIndex'"); + session.execute("INSERT INTO test.foo (i, j) VALUES (1, [8, 2.3, 58])"); + session.execute("INSERT INTO test.foo (i, j) VALUES (2, [1.2, 3.4, 5.6])"); + session.execute("INSERT INTO test.foo (i, j) VALUES (5, [23, 18, 3.9])"); + ResultSet rs=session.execute("SELECT j FROM test.foo WHERE j ann of [3.4, 7.8, 9.1] limit 1"); + for (Row row : rs){ + CqlVector v = row.getVector(0, Float.class); + System.out.println(v); + if (Iterables.size(v) != 3) { + throw new RuntimeException("Expected vector with three dimensions"); + } + } +} +``` + +You can also use the `CqlVector` type with prepared statements: + +```java +PreparedStatement preparedInsert = session.prepare("INSERT INTO test.foo (i, j) VALUES (?,?)"); +CqlVector vector = CqlVector.newInstance(1.4f, 2.5f, 3.6f); +session.execute(preparedInsert.bind(3, vector)); +``` + +In some cases, it makes sense to access the vector directly as an array of some numerical type. This version +supports such use cases by providing a codec which translates a CQL vector to and from a primitive array. Only float arrays are supported. +You can find more information about this codec in the manual documentation on [custom codecs](../manual/core/custom_codecs/) + ### 4.15.0 #### CodecNotFoundException now extends DriverException @@ -15,7 +70,7 @@ a logic such as below, it won't compile anymore: ```java try { - doSomethingWithDriver(); + doSomethingWithDriver(); } catch(DriverException e) { } catch(CodecNotFoundException e) { } @@ -25,7 +80,7 @@ You need to either reverse the catch order and catch `CodecNotFoundException` fi ```java try { - doSomethingWithDriver(); + doSomethingWithDriver(); } catch(CodecNotFoundException e) { } catch(DriverException e) { } @@ -35,7 +90,7 @@ Or catch only `DriverException`: ```java try { - doSomethingWithDriver(); + doSomethingWithDriver(); } catch(DriverException e) { } ``` @@ -229,16 +284,16 @@ The above can also be achieved by an adapter class as shown below: ```java public class NodeFilterToDistanceEvaluatorAdapter implements NodeDistanceEvaluator { - private final Predicate nodeFilter; + private final Predicate nodeFilter; - public NodeFilterToDistanceEvaluatorAdapter(@NonNull Predicate nodeFilter) { - this.nodeFilter = nodeFilter; - } + public NodeFilterToDistanceEvaluatorAdapter(@NonNull Predicate nodeFilter) { + this.nodeFilter = nodeFilter; + } - @Nullable @Override - public NodeDistance evaluateDistance(@NonNull Node node, @Nullable String localDc) { - return nodeFilter.test(node) ? null : NodeDistance.IGNORED; - } + @Nullable @Override + public NodeDistance evaluateDistance(@NonNull Node node, @Nullable String localDc) { + return nodeFilter.test(node) ? null : NodeDistance.IGNORED; + } } ``` @@ -531,7 +586,7 @@ import com.datastax.driver.core.Row; import com.datastax.driver.core.SimpleStatement; SimpleStatement statement = - new SimpleStatement("SELECT release_version FROM system.local"); + new SimpleStatement("SELECT release_version FROM system.local"); ResultSet resultSet = session.execute(statement); Row row = resultSet.one(); System.out.println(row.getString("release_version")); @@ -543,7 +598,7 @@ import com.datastax.oss.driver.api.core.cql.Row; import com.datastax.oss.driver.api.core.cql.SimpleStatement; SimpleStatement statement = - SimpleStatement.newInstance("SELECT release_version FROM system.local"); + SimpleStatement.newInstance("SELECT release_version FROM system.local"); ResultSet resultSet = session.execute(statement); Row row = resultSet.one(); System.out.println(row.getString("release_version")); @@ -606,9 +661,9 @@ datastax-java-driver { // Application code: SimpleStatement statement1 = - SimpleStatement.newInstance("...").setExecutionProfileName("profile1"); + SimpleStatement.newInstance("...").setExecutionProfileName("profile1"); SimpleStatement statement2 = - SimpleStatement.newInstance("...").setExecutionProfileName("profile2"); + SimpleStatement.newInstance("...").setExecutionProfileName("profile2"); ``` The configuration can be reloaded periodically at runtime: @@ -727,13 +782,13 @@ propagating its own consistency level to its bound statements: ```java PreparedStatement ps1 = - session.prepare( - SimpleStatement.newInstance("SELECT * FROM product WHERE sku = ?") - .setConsistencyLevel(DefaultConsistencyLevel.ONE)); + session.prepare( + SimpleStatement.newInstance("SELECT * FROM product WHERE sku = ?") + .setConsistencyLevel(DefaultConsistencyLevel.ONE)); PreparedStatement ps2 = - session.prepare( - SimpleStatement.newInstance("SELECT * FROM product WHERE sku = ?") - .setConsistencyLevel(DefaultConsistencyLevel.TWO)); + session.prepare( + SimpleStatement.newInstance("SELECT * FROM product WHERE sku = ?") + .setConsistencyLevel(DefaultConsistencyLevel.TWO)); assert ps1 != ps2; @@ -834,8 +889,8 @@ Optional ks = metadata.getKeyspace("test"); assert !ks.isPresent(); session.execute( - "CREATE KEYSPACE IF NOT EXISTS test " - + "WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1}"); + "CREATE KEYSPACE IF NOT EXISTS test " + + "WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1}"); // This is still the same metadata from before the CREATE ks = metadata.getKeyspace("test");