Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
37 changes: 37 additions & 0 deletions scripts/integrations.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,43 @@ test('all logo references have provenance, existing files, matching hashes and p
const manifest = JSON.parse(read('public/images/integrations/manifest.json'));
for (const i of integrations) assert.ok(manifest.assets[i.logo],`Missing logo record: ${i.logo}`);
});
test('Qdrant Java uses released Central coordinates and a complete blocking example', () => {
const page = read('src/pages/docs/integrations/traceai/java/vector-databases.mdx');
const section = page.split('## Qdrant\n')[1].split('\n## Milvus')[0];
assert.match(section, /<groupId>com\.futureagi<\/groupId>/);
assert.match(section, /<artifactId>traceai-java-qdrant<\/artifactId>\s*<version>1\.0\.0<\/version>/);
assert.match(section, /implementation 'com\.futureagi:traceai-java-qdrant:1\.0\.0'/);
assert.match(section, /implementation 'io\.qdrant:client:1\.16\.2'/);
const gradle = section.match(/```groovy Gradle\n([\s\S]*?)```/)[1];
assert.match(gradle, /repositories\s*\{\s*mavenCentral\(\)\s*\}/);
assert.match(gradle, /dependencies\s*\{/);
assert.doesNotMatch(gradle, /traceai-java-core/);
assert.match(page, /For Qdrant, follow the Maven Central installation below \*\*instead of\*\* that page's JitPack installation/);
assert.match(section, /Replace any existing JitPack TraceAI core and Qdrant dependencies/);
assert.match(section, /com\.futureagi:traceai-java-core:1\.0\.0` transitively/);
assert.doesNotMatch(section, /main-SNAPSHOT|com\.github\.future-agi/);
assert.match(section, /blocking methods/);
assert.match(section, /unwrap\(\).*bypass/);
assert.match(section, /public class QdrantExample/);
assert.match(section, /import io\.qdrant\.client\.grpc\.Collections\.Distance;/);
assert.match(section, /TraceAI\.shutdown\(\)/);
assert.doesNotMatch(section, /queryVector|pointsList|queryAsync\(/);
});
test('Qdrant Java configures export and discloses the pinned upsert metadata limitation', () => {
const page = read('src/pages/docs/integrations/traceai/java/vector-databases.mdx');
const section = page.split('## Qdrant\n')[1].split('\n## Milvus')[0];
const environment = section.match(/```bash\n([\s\S]*?)```/)[1];
assert.match(environment, /^export FI_BASE_URL="https:\/\/api\.futureagi\.com"$/m);
assert.match(environment, /^export FI_API_KEY="your-fi-api-key"$/m);
assert.match(environment, /^export FI_SECRET_KEY="your-fi-secret-key"$/m);
assert.match(section, /credentials alone do not enable span export/);
assert.match(section, /<Warning>\s*With `traceai-java-qdrant:1\.0\.0` and Qdrant SDK `1\.16\.2`/);
assert.match(section, /"Qdrant Upsert" spans incorrectly report `embedding\.dimensions` as `0`/);
assert.match(section, /Do not rely on this upsert field/);
assert.match(section, /use your collection configuration instead/);
assert.match(page, /\| `embedding\.dimensions` \|[^\n]*\[Qdrant limitation\]\(#qdrant\)/);
});

test('machine-readable overview serializes every catalog entry and setup aid', () => {
const text = integrationDirectoryMarkdown();
for (const entry of integrations) {
Expand Down
79 changes: 61 additions & 18 deletions src/pages/docs/integrations/traceai/java/vector-databases.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,48 +13,87 @@ description: "Trace vector database operations in Java. Qdrant, Milvus, ChromaDB

## Prerequisites

For Elasticsearch, follow the self-contained [native setup](#elasticsearch) below. For the other wrappers, complete the [Java SDK setup](/docs/integrations/traceai/java) first. For Pinecone, see the [dedicated Pinecone page](/docs/integrations/traceai/java/pinecone).
Use Java 17+ and your Future AGI API key and secret key. The [Java SDK setup](/docs/integrations/traceai/java) describes authentication and configuration. For Qdrant, follow the Maven Central installation below **instead of** that page's JitPack installation.

For Elasticsearch, follow the self-contained [native setup](#elasticsearch) below. For the other wrappers, complete the Java SDK setup first. For Pinecone, see the [dedicated Pinecone page](/docs/integrations/traceai/java/pinecone).

---

## Qdrant

Wraps `io.qdrant.client.QdrantClient`. All operations are async internally (the wrapper calls `.get()` on futures).
Trace searches, writes, point retrieval, and collection operations through `TracedQdrantClient`. Version 1.0.0 exposes blocking methods: each call waits for the underlying Qdrant future to complete. Calls made directly on the original client or through `unwrap()` bypass this wrapper.

Replace any existing JitPack TraceAI core and Qdrant dependencies with the Maven Central dependencies below; do not keep both sets of dependencies. The adapter brings `com.futureagi:traceai-java-core:1.0.0` transitively, so you do not need a separate core dependency. Add the Qdrant SDK explicitly. No JitPack repository is required.

<CodeGroup titles={["Maven", "Gradle"]}>

```xml Maven
<dependency>
<groupId>com.github.future-agi.traceAI</groupId>
<groupId>com.futureagi</groupId>
<artifactId>traceai-java-qdrant</artifactId>
<version>main-SNAPSHOT</version>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>io.qdrant</groupId>
<artifactId>client</artifactId>
<version>1.16.2</version>
</dependency>
```

```groovy Gradle
implementation 'com.github.future-agi.traceAI:traceai-java-qdrant:main-SNAPSHOT'
repositories {
mavenCentral()
}

dependencies {
implementation 'com.futureagi:traceai-java-qdrant:1.0.0'
implementation 'io.qdrant:client:1.16.2'
}
```

</CodeGroup>

Set all three environment variables before running the example. `FI_BASE_URL` is required to enable the exporter; credentials alone do not enable span export.

```bash
export FI_BASE_URL="https://api.futureagi.com"
export FI_API_KEY="your-fi-api-key"
export FI_SECRET_KEY="your-fi-secret-key"
```

With Qdrant running locally on gRPC port 6334, run this example once to create and search a demo collection. If the collection already exists, omit the `createCollection` call.

```java
import ai.traceai.TraceAI;
import ai.traceai.TraceConfig;
import ai.traceai.qdrant.TracedQdrantClient;
import io.qdrant.client.QdrantClient;
import io.qdrant.client.QdrantGrpcClient;
import io.qdrant.client.grpc.Collections.Distance;
import io.qdrant.client.grpc.Points.PointStruct;
import java.util.List;

QdrantClient client = new QdrantClient(
QdrantGrpcClient.newBuilder("localhost", 6334, false).build()
);
TracedQdrantClient traced = new TracedQdrantClient(client);

// Search
var results = traced.search("my-collection", queryVector, 10);

// Upsert
traced.upsert("my-collection", pointsList);
import static io.qdrant.client.PointIdFactory.id;
import static io.qdrant.client.VectorsFactory.vectors;

// Create collection
traced.createCollection("my-collection", 1536, Distance.Cosine);
public class QdrantExample {
public static void main(String[] args) throws Exception {
TraceAI.init(TraceConfig.builder().projectName("qdrant-java").build());
try (QdrantClient client = new QdrantClient(
QdrantGrpcClient.newBuilder("localhost", 6334, false).build())) {
TracedQdrantClient traced = new TracedQdrantClient(client);
String collection = "traceai-qdrant-example";
List<Float> vector = List.of(0.1f, 0.2f, 0.3f);
traced.createCollection(collection, 3, Distance.Cosine);
traced.upsert(collection, List.of(PointStruct.newBuilder()
.setId(id(1)).setVectors(vectors(vector)).build()));
var results = traced.search(collection, vector, 3);
System.out.println("Matches: " + results.size());
} finally {
TraceAI.shutdown();
}
}
}
```

**Spans:** "Qdrant Search" (RETRIEVER), "Qdrant Upsert" (VECTOR_DB), "Qdrant Create Collection" (VECTOR_DB), "Qdrant Delete" (VECTOR_DB), "Qdrant Get" (VECTOR_DB), "Qdrant List Collections" (VECTOR_DB)
Expand All @@ -63,6 +102,10 @@ Open your project in Future AGI to inspect the spans.

Extra attributes: `qdrant.top_score`, `qdrant.has_filter`, `qdrant.distance`, `qdrant.status`

<Warning>
With `traceai-java-qdrant:1.0.0` and Qdrant SDK `1.16.2`, "Qdrant Upsert" spans incorrectly report `embedding.dimensions` as `0` for dense vectors created by `VectorsFactory.vectors(List<Float>)`, including the three-dimensional vector above. Do not rely on this upsert field for dimension validation or filtering; use your collection configuration instead. Search spans report `embedding.dimensions` correctly, and collection-creation spans report the configured size in `qdrant.vector_size`.
</Warning>

---

## Milvus
Expand Down Expand Up @@ -630,6 +673,6 @@ Depending on the wrapper and operation, spans may include:
|-----------|-------------|
| `db.system` | Database name (e.g., `pinecone`, `qdrant`, `milvus`) |
| `db.vector.collection.name` or `db.vector.index.name` | Collection or index name |
| `embedding.dimensions` | Vector dimensions |
| `embedding.dimensions` | Vector dimensions; do not rely on this field for Qdrant upserts with the versions above (see the [Qdrant limitation](#qdrant)) |
| `retriever.top_k` | Number of results requested (search operations) |
| `db.vector.results.count` | Number of results returned |
Loading