diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs
index 090d14b19..65349222c 100644
--- a/scripts/integrations.test.mjs
+++ b/scripts/integrations.test.mjs
@@ -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'));
diff --git a/src/pages/docs/integrations/traceai/java/vector-databases.mdx b/src/pages/docs/integrations/traceai/java/vector-databases.mdx
index 014aa694b..087a18a82 100644
--- a/src/pages/docs/integrations/traceai/java/vector-databases.mdx
+++ b/src/pages/docs/integrations/traceai/java/vector-databases.mdx
@@ -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.
```xml Maven
- com.github.future-agi.traceAI
+ com.futureagi
traceai-java-pgvector
- main-SNAPSHOT
+ 1.0.0
+
+
+ com.pgvector
+ pgvector
+ 0.1.6
+
+
+ org.postgresql
+ postgresql
+ 42.7.14
```
```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'
```
-```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);
+
+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.
+
-// 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"));
+
+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.
+
-// 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.
+
`searchWithFilter` inserts the filter into SQL without binding its values. Use only trusted, fixed SQL; never concatenate untrusted input into the filter.
**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.
---