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
31 changes: 31 additions & 0 deletions scripts/integrations.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,37 @@ test('Anthropic Java recommends one native tracing owner and preserves released
}
});

test('Java pgvector uses released Central packages and connection-local type registration', () => {
const page = read('src/pages/docs/integrations/traceai/java/vector-databases.mdx');
const section = page.split('## pgvector\n')[1].split('## Azure AI Search')[0];
assert.match(section, /com\.futureagi:traceai-java-pgvector:1\.0\.0/);
assert.match(section, /com\.pgvector:pgvector:0\.1\.6/);
assert.match(section, /org\.postgresql:postgresql:42\.7\.14/);
assert.doesNotMatch(section, /main-SNAPSHOT|com\.github\.future-agi/);
assert.match(section, /try \(Connection connection = ds\.getConnection\(\)\)/);
assert.match(section, /new TracedPgVectorStore\(connection\)/);
assert.match(section, /PGvector\.registerTypes\(connection\)/);
assert.ok(section.indexOf('PGvector.registerTypes(connection)') < section.indexOf('traced.search('));
assert.match(section, /each connection/);
assert.match(section, /arbitrary SQL/);
assert.match(section, /never concatenate untrusted input/);
assert.match(section, /float\[\] vector = \{1\.0f, 2\.0f, 3\.0f\}/);
});

test('Java pgvector qualifies successful-operation privacy and hides database error details before use', () => {
const page = read('src/pages/docs/integrations/traceai/java/vector-databases.mdx');
const section = page.split('## pgvector\n')[1].split('## Azure AI Search')[0];
assert.match(section, /During successful operations, the store does not add embeddings or document metadata as span attributes/);
assert.doesNotMatch(section, /Embeddings and document metadata are not added to these spans/);
assert.match(section, /PostgreSQL error details can contain row values, including embeddings and document metadata/);
assert.match(section, /`FI_HIDE_ERROR_DETAILS=true` before initializing TraceAI/);
assert.match(section, /TraceConfig\.builder\(\)\.hideErrorDetails\(true\)\.build\(\)/);
assert.match(section, /`TraceAI\.init\(\.\.\.\)`/);
assert.match(section, /error messages, stack traces, and status descriptions/);
assert.match(section, /preserving ERROR status and exception types/);
assert.ok(section.indexOf('FI_HIDE_ERROR_DETAILS=true') < section.indexOf('new TracedPgVectorStore(connection)'));
});

test('public prose and catalog labels contain no internal QA label or Alpha release status', () => {
for (const file of routeFiles.filter(f=>f.endsWith('.mdx'))) {
const prose=publicProse(fs.readFileSync(file,'utf8'));
Expand Down
77 changes: 54 additions & 23 deletions src/pages/docs/integrations/traceai/java/vector-databases.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -302,56 +302,87 @@ Extra attributes: `redis.vector_field`, `redis.distance_metric`, `redis.algorith

## pgvector

Wraps `javax.sql.DataSource` or `java.sql.Connection` directly. Handles table creation, indexing, search with all three distance functions, and batch operations.
Trace inserts and similarity searches through `TracedPgVectorStore`, a store for tables with `id TEXT`, `embedding vector`, and `metadata JSONB` columns. It accepts a `DataSource` or `Connection` and traces only operations you call through the store. To trace existing applications with different schemas or arbitrary SQL, use [OpenTelemetry Java agent JDBC instrumentation](https://opentelemetry.io/docs/zero-code/java/agent/supported-libraries/) instead; JDBC spans do not add this store's retrieval attributes.

Install the store from Maven Central, plus pgvector-java and the PostgreSQL JDBC driver. Complete the [Java SDK setup](/docs/integrations/traceai/java) to configure your Future AGI project and tracer before using the store.

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

```xml Maven
<dependency>
<groupId>com.github.future-agi.traceAI</groupId>
<groupId>com.futureagi</groupId>
<artifactId>traceai-java-pgvector</artifactId>
<version>main-SNAPSHOT</version>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>com.pgvector</groupId>
<artifactId>pgvector</artifactId>
<version>0.1.6</version>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>42.7.14</version>
</dependency>
```

```groovy Gradle
implementation 'com.github.future-agi.traceAI:traceai-java-pgvector:main-SNAPSHOT'
repositories { mavenCentral() }
implementation 'com.futureagi:traceai-java-pgvector:1.0.0'
implementation 'com.pgvector:pgvector:0.1.6'
implementation 'org.postgresql:postgresql:42.7.14'
```

</CodeGroup>

```java
import ai.traceai.pgvector.TracedPgVectorStore;
import javax.sql.DataSource;

DataSource ds = /* your PostgreSQL DataSource */;
TracedPgVectorStore traced = new TracedPgVectorStore(ds);

// Create table
traced.createTable("documents", 1536);
<Warning>
PostgreSQL error details can contain row values, including embeddings and document metadata. Set `FI_HIDE_ERROR_DETAILS=true` before initializing TraceAI, or pass `TraceConfig.builder().hideErrorDetails(true).build()` to `TraceAI.init(...)`. This suppresses error messages, stack traces, and status descriptions recorded by traceAI while preserving ERROR status and exception types.
</Warning>

// Create index (supports ivfflat and hnsw)
traced.createIndex("documents", "hnsw", 100);
Set `JDBC_URL` to your PostgreSQL database URL and `DB_USER` and `DB_PASSWORD` to its credentials. Install the pgvector extension on your server first; `createTable` enables it in the database and needs permission to run `CREATE EXTENSION`.

// Insert
traced.insert("documents", "doc-1", vectorArray, Map.of("title", "Hello"));
<Note>
With `traceai-java-pgvector` 1.0.0, register pgvector types on **each connection** used for search. The example borrows a connection explicitly so registration and search use the same connection. Registering types once on an unrelated connection does not configure a pool.
</Note>

// Search (supports L2, cosine, inner product)
var results = traced.search("documents", queryVectorArray, 10, "cosine");
```java
import ai.traceai.pgvector.TracedPgVectorStore;
import com.pgvector.PGvector;
import org.postgresql.ds.PGSimpleDataSource;
import java.sql.Connection;
import java.util.Map;

// Search with filter
var filtered = traced.searchWithFilter("documents", queryVectorArray, 10, "cosine", "metadata->>'title' = 'Hello'");
PGSimpleDataSource ds = new PGSimpleDataSource();
ds.setURL(System.getenv("JDBC_URL"));
ds.setUser(System.getenv("DB_USER"));
ds.setPassword(System.getenv("DB_PASSWORD"));

try (Connection connection = ds.getConnection()) {
TracedPgVectorStore traced = new TracedPgVectorStore(connection);
traced.createTable("documents", 3);
PGvector.registerTypes(connection);
traced.createIndex("documents", "hnsw", 16);

float[] vector = {1.0f, 2.0f, 3.0f};
traced.insert("documents", "doc-1", vector, Map.of("title", "Hello"));
var results = traced.search("documents", vector, 10, "cosine");
var filtered = traced.searchWithFilter(
"documents", vector, 10, "cosine", "metadata->>'title' = 'Hello'");
System.out.println(results.get(0).getId());
}
```

The store leaves caller-owned connections open and does not commit their transactions. Close the connection in your application, as the example does. When you pass a `DataSource` instead, each operation borrows and closes its own connection.

<Warning>
`searchWithFilter` inserts the filter into SQL without binding its values. Use only trusted, fixed SQL; never concatenate untrusted input into the filter.
</Warning>

**Spans:** "PgVector Search" (RETRIEVER), "PgVector Insert" (VECTOR_DB), "PgVector Batch Insert" (VECTOR_DB), "PgVector Create Table" (VECTOR_DB), "PgVector Create Index" (VECTOR_DB), plus delete, count, and drop operations.

Extra attributes: `pgvector.distance_function`, `pgvector.index_type`, `pgvector.has_filter`
Open your project in Future AGI and inspect the "PgVector Search" span. It includes the collection name, requested result count, returned result count, and `pgvector.distance_function`. During successful operations, the store does not add embeddings or document metadata as span attributes.

Distance operators: `<->` (L2), `<=>` (cosine), `<#>` (inner product)
Distance functions: `l2` (`<->`), `cosine` (`<=>`), and `inner_product` (`<#>`). Results contain distances, not similarity scores; the inner-product operator returns the negative inner product.

---

Expand Down
Loading