From d4bb60447dcf0926af28fa2ceb8335c13e391cb0 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek <8347993+nik13@users.noreply.github.com> Date: Sat, 31 Oct 2026 10:17:14 -0700 Subject: [PATCH 1/2] fix(pgvector-java): document released Central setup and connection registration Co-Authored-By: Claude Code --- scripts/integrations.test.mjs | 17 ++++ .../traceai/java/vector-databases.mdx | 77 +++++++++++++------ 2 files changed, 69 insertions(+), 25 deletions(-) diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index 0a8e2c289..7722ded78 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -58,6 +58,23 @@ test('machine-readable overview serializes every catalog entry and setup aid', ( assert.equal(integrations.find(i => i.id === 'eve').name, 'Eve'); assert.doesNotMatch(read('src/components/IntegrationDirectory.astro'), /↗/); }); +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('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 6e9610bc5..b297e3142 100644 --- a/src/pages/docs/integrations/traceai/java/vector-databases.mdx +++ b/src/pages/docs/integrations/traceai/java/vector-databases.mdx @@ -301,56 +301,83 @@ 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; +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`. -DataSource ds = /* your PostgreSQL DataSource */; -TracedPgVectorStore traced = new TracedPgVectorStore(ds); + +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. + -// Create table -traced.createTable("documents", 1536); - -// Create index (supports ivfflat and hnsw) -traced.createIndex("documents", "hnsw", 100); - -// Insert -traced.insert("documents", "doc-1", vectorArray, Map.of("title", "Hello")); - -// Search (supports L2, cosine, inner product) -var results = traced.search("documents", queryVectorArray, 10, "cosine"); - -// Search with filter -var filtered = traced.searchWithFilter("documents", queryVectorArray, 10, "cosine", "metadata->>'title' = 'Hello'"); +```java +import ai.traceai.pgvector.TracedPgVectorStore; +import com.pgvector.PGvector; +import org.postgresql.ds.PGSimpleDataSource; +import java.sql.Connection; +import java.util.Map; + +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`. Embeddings and document metadata are not added to these spans. -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. --- From eca01f2db9c1cfa2d50dd4291952a8792d8059fe Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Wed, 4 Nov 2026 07:29:56 -0800 Subject: [PATCH 2/2] fix(pgvector-java): qualify privacy guarantees for database errors Document the released error-detail privacy controls before store initialization and limit the no-content claim to successful operation attributes. Add a documentation regression test for the warning and both configuration paths. Co-Authored-By: Claude Code --- scripts/integrations.test.mjs | 14 ++++++++++++++ .../integrations/traceai/java/vector-databases.mdx | 6 +++++- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index efe87cb0d..65349222c 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -198,6 +198,20 @@ test('Java pgvector uses released Central packages and connection-local type reg 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 8e0ff6018..087a18a82 100644 --- a/src/pages/docs/integrations/traceai/java/vector-databases.mdx +++ b/src/pages/docs/integrations/traceai/java/vector-databases.mdx @@ -335,6 +335,10 @@ implementation 'org.postgresql:postgresql:42.7.14' + +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. + + 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`. @@ -376,7 +380,7 @@ The store leaves caller-owned connections open and does not commit their transac **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. -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`. Embeddings and document metadata are not added to these spans. +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 functions: `l2` (`<->`), `cosine` (`<=>`), and `inner_product` (`<#>`). Results contain distances, not similarity scores; the inner-product operator returns the negative inner product.