Skip to content

Commit bc97df3

Browse files
clunclun
committed
vectorize:
1 parent 04b309e commit bc97df3

34 files changed

+701
-208
lines changed

‎REALEASE.MD

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
2+
[![License Apache2](https://img.shields.io/hexpm/l/plug.svg)](http://www.apache.org/licenses/LICENSE-2.0)
3+
4+
This page is mean to help developer to release this the SDK.
5+
6+
## Run the Test
7+
8+
### Prerequisites
9+
10+
To run the tests you need 3 different environments: Dev, PROD and a local installation. For Astra DEV and production you should have the following environment variables sets: `ASTRA_DB_APPLICATION_TOKEN_DEV` and `ASTRA_DB_APPLICATION_TOKEN`.
11+
12+
- Generate Jacoco Report
13+
```json
14+
mvn clean test jacoco:report
15+
```
16+
17+
- Push to SONAR
18+
```json
19+
mvn verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar -Dsonar.projectKey=clun_astra-db-java
20+
```
21+

‎astra-db-java/pom.xml

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -230,6 +230,38 @@
230230
</configuration>
231231
</plugin>
232232

233+
<plugin>
234+
<groupId>org.jacoco</groupId>
235+
<artifactId>jacoco-maven-plugin</artifactId>
236+
<version>${version.maven.plugin.jacoco}</version>
237+
<executions>
238+
<execution>
239+
<id>default-prepare-agent</id>
240+
<goals>
241+
<goal>prepare-agent</goal>
242+
</goals>
243+
</execution>
244+
<execution>
245+
<id>default-prepare-agent-integration</id>
246+
<goals>
247+
<goal>prepare-agent-integration</goal>
248+
</goals>
249+
</execution>
250+
<execution>
251+
<id>default-report</id>
252+
<goals>
253+
<goal>report</goal>
254+
</goals>
255+
</execution>
256+
<execution>
257+
<id>default-report-integration</id>
258+
<goals>
259+
<goal>report-integration</goal>
260+
</goals>
261+
</execution>
262+
</executions>
263+
</plugin>
264+
233265
<plugin>
234266
<groupId>org.apache.maven.plugins</groupId>
235267
<artifactId>maven-dependency-plugin</artifactId>

‎astra-db-java/src/main/java/com/datastax/astra/client/Collection.java

Lines changed: 53 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -23,15 +23,18 @@
2323
import com.datastax.astra.client.exception.DataApiException;
2424
import com.datastax.astra.client.exception.DataApiFaultyResponseException;
2525
import com.datastax.astra.client.exception.TooManyDocumentsToCountException;
26-
import com.datastax.astra.client.model.Command;
27-
import com.datastax.astra.client.model.Document;
28-
import com.datastax.astra.internal.ApiResponse;
29-
import com.datastax.astra.client.model.CollectionDefinition;
26+
import com.datastax.astra.client.model.BulkWriteOptions;
27+
import com.datastax.astra.client.model.BulkWriteResult;
28+
import com.datastax.astra.client.model.CollectionInfo;
3029
import com.datastax.astra.client.model.CollectionOptions;
30+
import com.datastax.astra.client.model.Command;
3131
import com.datastax.astra.client.model.DeleteOneOptions;
3232
import com.datastax.astra.client.model.DeleteResult;
33+
import com.datastax.astra.client.model.DistinctIterable;
34+
import com.datastax.astra.client.model.Document;
3335
import com.datastax.astra.client.model.Filter;
3436
import com.datastax.astra.client.model.Filters;
37+
import com.datastax.astra.client.model.FindIterable;
3538
import com.datastax.astra.client.model.FindOneAndDeleteOptions;
3639
import com.datastax.astra.client.model.FindOneAndReplaceOptions;
3740
import com.datastax.astra.client.model.FindOneAndReplaceResult;
@@ -41,16 +44,13 @@
4144
import com.datastax.astra.client.model.InsertManyOptions;
4245
import com.datastax.astra.client.model.InsertManyResult;
4346
import com.datastax.astra.client.model.InsertOneResult;
44-
import com.datastax.astra.client.model.DistinctIterable;
45-
import com.datastax.astra.client.model.FindIterable;
4647
import com.datastax.astra.client.model.Page;
47-
import com.datastax.astra.client.model.BulkWriteOptions;
48-
import com.datastax.astra.client.model.BulkWriteResult;
4948
import com.datastax.astra.client.model.ReplaceOneOptions;
5049
import com.datastax.astra.client.model.Update;
5150
import com.datastax.astra.client.model.UpdateOneOptions;
5251
import com.datastax.astra.client.model.UpdateResult;
5352
import com.datastax.astra.internal.AbstractCommandRunner;
53+
import com.datastax.astra.internal.ApiResponse;
5454
import com.datastax.astra.internal.utils.Assert;
5555
import com.datastax.astra.internal.utils.JsonUtils;
5656
import lombok.Getter;
@@ -78,16 +78,18 @@
7878

7979
/**
8080
* A Data API collection, the main object to interact with the Data API, especially for DDL operations.
81-
* This class has a synchronous and asynchronous signature for all operations.
8281
* <p>
83-
* A Collection is spawned from a DataApiNameSpace object, from which it inherits the details on how to reach the API server
82+
* A Collection is spawned from a Database object, from which it inherits the details on how to reach the API server
8483
* (endpoint, authentication). A Collection has a name, which is its unique identifier for a namespace and
8584
* options to specialize the usage as vector collections or advanced indexing parameters.
8685
* </p>
8786
* <p>
8887
* A Collection is typed object designed to work both with default @{@link Document} (wrapper for a Map) and application
8988
* plain old java objects (pojo). The serialization is performed with Jackson and application beans can be annotated.
9089
* </p>
90+
* <p>
91+
* All features are provided in synnchronous and asynchronous flavore
92+
* </p>
9193
* <p>Example usage:</p>
9294
* <pre>
9395
* {@code
@@ -120,7 +122,7 @@ public class Collection<DOC> extends AbstractCommandRunner {
120122
private final Database database;
121123

122124
/** Api Endpoint for the Database. */
123-
private final String apiEndpointCollection;
125+
private final String apiEndpoint;
124126

125127
/**
126128
* Full constructor.
@@ -139,7 +141,7 @@ protected Collection(Database db, String collectionName, Class<DOC> clazz) {
139141
this.collectionName = collectionName;
140142
this.database = db;
141143
this.documentClass = clazz;
142-
this.apiEndpointCollection = db.getApiEndpointDatabase() + "/" + collectionName;
144+
this.apiEndpoint = db.getApiEndpoint() + "/" + collectionName;
143145
}
144146

145147
// ----------------------------
@@ -174,7 +176,7 @@ public String getNamespaceName() {
174176
*
175177
* @return the full collection definition
176178
*/
177-
public CollectionDefinition getDefinition() {
179+
public CollectionInfo getDefinition() {
178180
return database
179181
.listCollections()
180182
.filter(col -> col.getName().equals(collectionName))
@@ -461,20 +463,6 @@ public Optional<DOC> findOne(Filter filter, FindOneOptions options) {
461463
.map(getDocumentClass()));
462464
}
463465

464-
/**
465-
* Finds all documents in the collection.
466-
*
467-
* @param filter
468-
* the query filter
469-
* @param options
470-
* options of find one
471-
* @return
472-
* the find iterable interface
473-
*/
474-
public FindIterable<DOC> find(Filter filter, FindOptions options) {
475-
return new FindIterable<>(this, filter, options);
476-
}
477-
478466
/**
479467
* Initiates an asynchronous search to find a single document that matches the given filter criteria.
480468
* This method leverages the functionality of to perform the
@@ -511,6 +499,20 @@ public Optional<DOC> findById(Object id) {
511499
return findOne(Filters.eq(id));
512500
}
513501

502+
/**
503+
* Finds all documents in the collection.
504+
*
505+
* @param filter
506+
* the query filter
507+
* @param options
508+
* options of find one
509+
* @return
510+
* the find iterable interface
511+
*/
512+
public FindIterable<DOC> find(Filter filter, FindOptions options) {
513+
return new FindIterable<>(this, filter, options);
514+
}
515+
514516
/**
515517
* Retrieves all documents in the collection.
516518
* <p>
@@ -553,7 +555,29 @@ public FindIterable<DOC> find(Filter filter) {
553555
* @return A {@link FindIterable} for iterating over the sorted and limited documents.
554556
*/
555557
public FindIterable<DOC> find(Filter filter, float[] vector, int limit) {
556-
return find(filter, new FindOptions().sortingByVector(vector).limit(limit));
558+
return find(filter, FindOptions.builder()
559+
.withVector(vector)
560+
.limit(limit)
561+
.build());
562+
}
563+
564+
/**
565+
* Finds documents in the collection that match the specified filter and sorts them based on their similarity
566+
* to a provided vector, limiting the number of results returned.
567+
* <p>
568+
* This method leverage the 'vectorization' to compute the embeddings on the fly in order to execute the search.
569+
* </p>
570+
*
571+
* @param filter The query filter to apply when retrieving documents.
572+
* @param vectorize A float array representing the vector used to sort the documents.
573+
* @param limit The maximum number of documents to return.
574+
* @return A {@link FindIterable} for iterating over the sorted and limited documents.
575+
*/
576+
public FindIterable<DOC> find(Filter filter, String vectorize, int limit) {
577+
return find(filter, FindOptions.builder()
578+
.withVectorize(vectorize)
579+
.limit(limit)
580+
.build());
557581
}
558582

559583
/**
@@ -1271,7 +1295,7 @@ public BulkWriteResult bulkWrite(List<Command> commands, BulkWriteOptions option
12711295
/** {@inheritDoc} */
12721296
@Override
12731297
protected String getApiEndpoint() {
1274-
return apiEndpointCollection;
1298+
return apiEndpoint;
12751299
}
12761300

12771301
/** {@inheritDoc} */

‎astra-db-java/src/main/java/com/datastax/astra/client/DataAPIClient.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -141,9 +141,9 @@ public Database getDatabase(UUID databaseId, String namespace) {
141141
Assert.notNull(databaseId, "databaseId");
142142
Assert.hasLength(namespace, "namespace");
143143
return new Database(new AstraApiEndpoint(databaseId,
144-
getAdmin().getDatabaseInformations(databaseId).getInfo().getRegion(),
144+
getAdmin().getDatabaseInfo(databaseId).getRegion(),
145145
getAstraEnvironment()).getApiEndPoint(),
146-
namespace);
146+
this.token, namespace);
147147
}
148148

149149
/**

‎astra-db-java/src/main/java/com/datastax/astra/client/Database.java

Lines changed: 29 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
import com.datastax.astra.client.admin.DatabaseAdmin;
2626
import com.datastax.astra.client.model.Command;
2727
import com.datastax.astra.client.model.Document;
28-
import com.datastax.astra.client.model.CollectionDefinition;
28+
import com.datastax.astra.client.model.CollectionInfo;
2929
import com.datastax.astra.client.model.CollectionOptions;
3030
import com.datastax.astra.client.model.SimilarityMetric;
3131
import com.datastax.astra.internal.AbstractCommandRunner;
@@ -45,7 +45,14 @@
4545
import static com.datastax.astra.internal.utils.Assert.notNull;
4646

4747
/**
48-
* Class to interact with a Namespace.
48+
* A Data API database. This is the entry-point object for doing database-level
49+
* DML, such as creating/deleting collections, and for obtaining Collection
50+
* objects themselves. This class has a synchronous interface.
51+
* <p>
52+
* A Database comes with an "API Endpoint", which implies a Database object
53+
* instance reaches a specific region (relevant point in case of multi-region
54+
* databases).
55+
* </p>
4956
*/
5057
@Slf4j
5158
public class Database extends AbstractCommandRunner {
@@ -54,20 +61,21 @@ public class Database extends AbstractCommandRunner {
5461
@Getter
5562
private final String namespaceName;
5663

57-
/** Token to be use with the Database. */
64+
/** Token to be used with the Database. */
5865
private final String token;
5966

6067
/** Api Endpoint for the API. */
6168
private final String apiEndpoint;
6269

63-
/** Api Endpoint for the Database. */
64-
@Getter
65-
private final String apiEndpointDatabase;
66-
67-
/** Options to setup the client. */
70+
/** Options to set up the client. */
6871
@Getter
6972
private final DataAPIOptions options;
7073

74+
/**
75+
* This core endpoint could be used for admin operations.
76+
*/
77+
private final String databaseAdminEndpoint;
78+
7179
/**
7280
* Initialization with endpoint and apikey.
7381
*
@@ -113,8 +121,8 @@ public Database(String apiEndpoint, String token, String namespace, DataAPIOptio
113121
notNull(options, "options");
114122
this.namespaceName = namespace;
115123
this.token = token;
116-
this.apiEndpoint = apiEndpoint;
117124
this.options = options;
125+
this.databaseAdminEndpoint = apiEndpoint + "/" + options.getApiVersion();
118126
StringBuilder dbApiEndPointBuilder = new StringBuilder(apiEndpoint);
119127
switch(options.destination) {
120128
case ASTRA:
@@ -125,8 +133,12 @@ public Database(String apiEndpoint, String token, String namespace, DataAPIOptio
125133
}
126134
break;
127135
}
128-
dbApiEndPointBuilder.append("/").append(options.getApiVersion()).append("/").append(namespaceName);
129-
this.apiEndpointDatabase = dbApiEndPointBuilder.toString();
136+
this.apiEndpoint = dbApiEndPointBuilder
137+
.append("/")
138+
.append(options.getApiVersion())
139+
.append("/")
140+
.append(namespaceName)
141+
.toString();
130142
}
131143

132144
// ------------------------------------------
@@ -146,15 +158,15 @@ public DatabaseAdmin getDatabaseAdmin() {
146158
* Gets the name of the database.
147159
*
148160
* @param superUserToken
149-
* provide a token with super user role
161+
* provide a token with a super-user role
150162
* @return the database name
151163
*/
152164
public DatabaseAdmin getDatabaseAdmin(String superUserToken) {
153165
if (Objects.requireNonNull(options.getDestination()) == DataAPIDestination.ASTRA) {
154166
AstraApiEndpoint endpoint = AstraApiEndpoint.parse(apiEndpoint);
155167
return new AstraDBDatabaseAdmin(superUserToken, endpoint.getDatabaseId(), endpoint.getEnv(), options);
156168
}
157-
return new DataAPIDatabaseAdmin(apiEndpoint, token, options);
169+
return new DataAPIDatabaseAdmin(databaseAdminEndpoint, token, options);
158170
}
159171

160172
// ------------------------------------------
@@ -183,13 +195,13 @@ public Stream<String> listCollectionNames() {
183195
* @return
184196
* list of collection definitions
185197
*/
186-
public Stream<CollectionDefinition> listCollections() {
198+
public Stream<CollectionInfo> listCollections() {
187199
Command findCollections = Command
188200
.create("findCollections")
189201
.withOptions(new Document().append("explain", true));
190202

191203
return runCommand(findCollections)
192-
.getStatusKeyAsList("collections", CollectionDefinition.class)
204+
.getStatusKeyAsList("collections", CollectionInfo.class)
193205
.stream();
194206
}
195207

@@ -234,7 +246,7 @@ public Collection<Document> getCollection(String collectionName) {
234246
public <DOC> Collection<DOC> getCollection(String collectionName, @NonNull Class<DOC> documentClass) {
235247
hasLength(collectionName, "collectionName");
236248
notNull(documentClass, "documentClass");
237-
return new Collection<DOC>(this, collectionName, documentClass);
249+
return new Collection<>(this, collectionName, documentClass);
238250
}
239251

240252
/**
@@ -364,7 +376,7 @@ public void dropCollection(String collectionName) {
364376
/** {@inheritDoc} */
365377
@Override
366378
protected String getApiEndpoint() {
367-
return apiEndpointDatabase;
379+
return apiEndpoint;
368380
}
369381

370382
/** {@inheritDoc} */

0 commit comments

Comments
 (0)