Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

JAVA-3083 Doc updates for new features in 4.17.0 #1677

Merged
merged 15 commits into from
Jul 12, 2023
Merged

JAVA-3083 Doc updates for new features in 4.17.0 #1677

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
42ca91c
Data type table + upgrade guide updates
absurdfarce Jul 11, 2023
011ba56
Add info re: float array extra codec
absurdfarce Jul 11, 2023
3fd8c8d
Add pointer to custom codec docs for CqlVector
absurdfarce Jul 11, 2023
a0aecba
Formatting cleanup
absurdfarce Jul 11, 2023
8ce72ea
Feedback from code review
absurdfarce Jul 11, 2023
daa6c01
Another pass at the Java17 language
absurdfarce Jul 11, 2023
b332554
Update upgrade_guide/README.md
absurdfarce Jul 12, 2023
952f7e9
Update upgrade_guide/README.md
absurdfarce Jul 12, 2023
1eef3c2
Update upgrade_guide/README.md
absurdfarce Jul 12, 2023
cfaf73f
Update upgrade_guide/README.md
absurdfarce Jul 12, 2023
f81cdd9
Code review feedback
absurdfarce Jul 12, 2023
760c17d
Update manual/core/custom_codecs/README.md
absurdfarce Jul 12, 2023
100b325
Update upgrade_guide/README.md
absurdfarce Jul 12, 2023
82cca76
A few other minor cleanups
absurdfarce Jul 12, 2023
352d862
Merge branch '4.x' into java3083
absurdfarce Jul 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 30 additions & 28 deletions manual/core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<T> | |
| map | getMap | java.util.Map<K, V> | |
| set | getSet | java.util.Set<T> | |
| 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<T> | |
| map | getMap | java.util.Map<K, V> | |
| set | getSet | java.util.Set<T> | |
| 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/) |
hhughes marked this conversation as resolved.
Show resolved Hide resolved

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
Expand Down Expand Up @@ -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-
Expand Down
12 changes: 12 additions & 0 deletions manual/core/custom_codecs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>` | `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.
Expand Down Expand Up @@ -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
Expand Down
101 changes: 78 additions & 23 deletions upgrade_guide/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
jgillenwater marked this conversation as resolved.
Show resolved Hide resolved

#### 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<float, 3>)");
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<Float> v = row.getVector(0, Float.class);
System.out.println(v);
if (Iterables.size(v) != 3) {
throw new RuntimeException("Expected vector with three dimensions");
}
}
}
hhughes marked this conversation as resolved.
Show resolved Hide resolved
```

You can also use the `CqlVector` type with prepared statements:

```java
PreparedStatement preparedInsert = session.prepare("INSERT INTO test.foo (i, j) VALUES (?,?)");
CqlVector<Float> 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
Expand All @@ -15,7 +70,7 @@ a logic such as below, it won't compile anymore:

```java
try {
doSomethingWithDriver();
doSomethingWithDriver();
} catch(DriverException e) {
} catch(CodecNotFoundException e) {
}
Expand All @@ -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) {
}
Expand All @@ -35,7 +90,7 @@ Or catch only `DriverException`:

```java
try {
doSomethingWithDriver();
doSomethingWithDriver();
} catch(DriverException e) {
}
```
Expand Down Expand Up @@ -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<Node> nodeFilter;
private final Predicate<Node> nodeFilter;

public NodeFilterToDistanceEvaluatorAdapter(@NonNull Predicate<Node> nodeFilter) {
this.nodeFilter = nodeFilter;
}
public NodeFilterToDistanceEvaluatorAdapter(@NonNull Predicate<Node> 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;
}
}
```

Expand Down Expand Up @@ -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"));
Expand All @@ -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"));
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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;

Expand Down Expand Up @@ -834,8 +889,8 @@ Optional<KeyspaceMetadata> 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");
Expand Down
Loading