Graphile + pgvector Integration

Integrate pgvector with PostGraphile v5 (Grafast/graphile-build-pg) so that vector(n) columns are surfaced in GraphQL as a Vector scalar, and vector similarity search is available as first-class GraphQL query fields.

When to Apply

Use this skill when:

• Adding vector(n) columns to tables and need them visible in the PostGraphile schema
• Exposing vector similarity search (cosine, L2, inner product) as GraphQL queries
• Building AI/RAG features on top of a Constructive or PostGraphile v5 stack
• Writing integration tests for pgvector-backed GraphQL APIs

Two Moving Parts

Component	Package	What it does
VectorCodecPlugin	graphile-settings	Registers a codec for the vector PG type → Vector GraphQL scalar; makes embedding columns visible
PgVectorPlugin / PgVectorPreset	postgraphile-plugin-pgvector	Adds vectorSearch<Table> root query fields with query, limit, offset, metric args

Both must be in the preset for end-to-end vector support.

VectorCodecPlugin — Expose vector Columns as GraphQL Scalar

Without this plugin, PostGraphile silently ignores vector(n) columns. The codec teaches graphile-build-pg how to parse and serialize the type.

Wire Format

PostgreSQL sends vectors as text: [0.1,0.2,...,0.768] JavaScript representation: number[] GraphQL scalar: Vector (serialized as [Float])

Source Location

graphile-settings/src/plugins/vector-codec.ts — included automatically in ConstructivePreset.

Pure Helper Exports (Testable Standalone)

import { fromPgVector, toPgVector, vectorScalarConfig } from 'graphile-settings/plugins/vector-codec';

// Parse PG text → JS
fromPgVector('[0.1,0.2,0.3]'); // => [0.1, 0.2, 0.3]

// Serialize JS → PG text
toPgVector([0.1, 0.2, 0.3]); // => '[0.1,0.2,0.3]'

Plugin Structure

export const VectorCodecPlugin: GraphileConfig.Plugin = {
  name: 'VectorCodecPlugin',
  version: '1.0.0',

  // Gather phase: hook into codec discovery; register codec when type.typname === 'vector'
  gather: {
    hooks: {
      async pgCodecs_findPgCodec(info, event) {
        if (event.pgCodec) return;
        const { pgType: type, serviceName } = event;
        if (type.typname !== 'vector') return;
        // ... resolve namespace, build codec with fromPg/toPg, set event.pgCodec
      },
    },
  },

  // Schema phase: register Vector scalar and map the codec to it
  schema: {
    hooks: {
      init: {
        before: ['PgCodecs'],
        callback(_, build) {
          build.registerScalarType('Vector', {}, () => vectorScalarConfig, '...');
          for (const codec of Object.values(build.input.pgRegistry.pgCodecs)) {
            if ((codec as any).name === 'vector') {
              setGraphQLTypeForPgCodec(codec as any, 'input', 'Vector');
              setGraphQLTypeForPgCodec(codec as any, 'output', 'Vector');
            }
          }
          return _;
        },
      },
    },
  },
};

Key Hook: pgCodecs_findPgCodec

This gather hook fires for every unknown PG type. Return early if event.pgCodec is already set (already handled). Check type.typname === 'vector' and assign a codec with fromPg/toPg functions.

Key Hook: init (before PgCodecs)

Must run before PgCodecs processes the registry. Registers the Vector scalar and maps it to the codec for both input and output GraphQL roles.

---

PgVectorPlugin — Vector Search GraphQL Fields

Adds root query fields for similarity search across configured tables.

Installation

pnpm add postgraphile-plugin-pgvector

Usage — Preset (Recommended)

import { PgVectorPreset } from 'postgraphile-plugin-pgvector';

const preset: GraphileConfig.Preset = {
  extends: [
    ConstructivePreset,        // includes VectorCodecPlugin
    PgVectorPreset({
      collections: [
        {
          schema: 'public',
          table: 'documents',
          embeddingColumn: 'embedding',
          graphqlFieldName: 'vectorSearchDocument',  // optional; auto-generated if omitted
          maxQueryDim: 768,                          // optional defensive validation
        },
        {
          schema: 'public',
          table: 'contacts',
          embeddingColumn: 'embedding',
        },
      ],
      defaultMetric: 'COSINE',  // COSINE | L2 | IP
      maxLimit: 100,
    }),
  ],
};

Usage — Plugin Directly

import { PgVectorPlugin } from 'postgraphile-plugin-pgvector';

const plugin = PgVectorPlugin({
  collections: [{ schema: 'public', table: 'documents', embeddingColumn: 'embedding' }],
});

Generated GraphQL API

type Query {
  vectorSearchDocument(
    query: [Float!]!       # embedding vector (must match column dimensions)
    limit: Int             # default 10, capped at maxLimit
    offset: Int            # pagination
    metric: VectorMetric   # COSINE (default), L2, IP
  ): [DocumentVectorSearchResult!]!
}

enum VectorMetric { COSINE L2 IP }

type DocumentVectorSearchResult {
  distance: Float!   # distance score; lower = more similar for COSINE/L2
  id: Int!
  title: String!
  # ... all other table columns
}

GraphQL Query Example

query SearchDocuments($vector: [Float!]!) {
  vectorSearchDocument(query: $vector, limit: 5, metric: COSINE) {
    distance
    id
    title
    content
  }
}

Distance Metrics

Metric	Operator	Range	Notes
COSINE	<=>	0–2	0 = identical; recommended for normalized embeddings
L2	<->	0–∞	Euclidean distance
IP	<#>	−∞–0	Negative inner product; higher (less negative) = more similar

---

Codegen — Vector Type → number[]

When using @constructive-io/graphql-codegen, add the Vector scalar mapping so generated types use number[] instead of unknown:

// graphql-codegen.config.ts
export default createConfig({
  targets: [{
    // ...
    scalars: {
      Vector: 'number[]',
    },
  }],
});

With @constructive-io/graphql-codegen >= 4.6.0, Vector: 'number[]' is built-in to SCALAR_TS_MAP. For 4.2.0, apply a pnpm patch adding scalars?: Record<string, string> to the config type defs.

---

SQL Search Functions (Alternative: Direct SQL)

For route-level RAG (bypassing GraphQL), define SQL functions instead:

CREATE OR REPLACE FUNCTION your_schema.search_contacts(
  query_embedding vector(768),
  match_count int DEFAULT 10
)
RETURNS TABLE (
  id uuid,
  entity_id text,
  first_name text,
  last_name text,
  email text,
  headline text,
  similarity float
)
LANGUAGE sql STABLE
AS $$
  SELECT
    id, entity_id, first_name, last_name, email, headline,
    1 - (embedding <=> query_embedding) AS similarity
  FROM your_schema.contacts
  WHERE embedding IS NOT NULL
  ORDER BY embedding <=> query_embedding
  LIMIT match_count;
$$;

These are surfaced automatically in the GraphQL schema (PostGraphile computed columns / functions) if the naming and return type conventions match. The VectorCodecPlugin is still required so that the vector argument type resolves correctly.

---

Integration Tests

Use graphile-test's getConnections with real DB. No mocks.

// __tests__/pgvector.test.ts
import { join } from 'path';
import { getConnections, seed } from 'graphile-test';
import { PgVectorPreset } from 'postgraphile-plugin-pgvector';
import { ConstructivePreset } from 'graphile-settings';

describe('PgVectorPlugin', () => {
  let db: PgTestClient;
  let teardown: () => Promise<void>;
  let query: QueryFn;

  beforeAll(async () => {
    const testPreset = {
      extends: [
        ConstructivePreset,
        PgVectorPreset({
          collections: [{
            schema: 'pgvector_test',
            table: 'documents',
            embeddingColumn: 'embedding',
            graphqlFieldName: 'vectorSearchDocument',
          }],
        }),
      ],
    };

    const connections = await getConnections({
      schemas: ['pgvector_test'],
      preset: testPreset,
      useRoot: true,
    }, [
      seed.sqlfile([join(__dirname, './setup.sql')])
    ]);

    ({ db, teardown, query } = connections);
    await db.client.query('BEGIN');
  });

  afterAll(async () => {
    try { await db.client.query('ROLLBACK'); } catch {}
    await teardown();
  });

  beforeEach(() => db.beforeEach());
  afterEach(() => db.afterEach());

  it('returns vector search results ordered by distance', async () => {
    // Insert test doc with pre-computed embedding
    const embedding = Array(768).fill(0.1);
    await db.client.query(
      `INSERT INTO pgvector_test.documents (title, content, embedding)
       VALUES ($1, $2, $3::vector)`,
      ['Test Doc', 'Hello world', `[${embedding.join(',')}]`]
    );

    const result = await query<{ vectorSearchDocument: Array<{ title: string; distance: number }> }>(`
      query {
        vectorSearchDocument(query: [${embedding.join(',')}], limit: 5, metric: COSINE) {
          title
          distance
        }
      }
    `);

    expect(result.data?.vectorSearchDocument).toHaveLength(1);
    expect(result.data?.vectorSearchDocument[0].title).toBe('Test Doc');
    expect(result.data?.vectorSearchDocument[0].distance).toBeCloseTo(0, 5);
  });
});

Setup SQL

-- __tests__/setup.sql
CREATE SCHEMA IF NOT EXISTS pgvector_test;
CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE pgvector_test.documents (
  id SERIAL PRIMARY KEY,
  title TEXT NOT NULL,
  content TEXT,
  embedding vector(768),
  created_at TIMESTAMPTZ DEFAULT now()
);

CREATE INDEX ON pgvector_test.documents USING hnsw (embedding vector_cosine_ops);

Key graphile-test Pattern Notes

• getConnections({ schemas, preset, useRoot: true }, [seed.sqlfile([...])]) — no mocks
• graphile-test has MinimalPreset baked in; pass your plugin preset as extends
• SQL fixture must CREATE EXTENSION IF NOT EXISTS vector; before creating vector columns
• Use BEGIN / ROLLBACK for transaction-scoped test isolation (not beforeEach schema drops)

---

Codec-Only Usage (No Search Fields)

If you only need vector columns visible in the schema (not search fields), just include VectorCodecPlugin in your preset:

import { VectorCodecPlugin } from 'graphile-settings/plugins/vector-codec';
// or use ConstructivePreset which includes it automatically

const preset = {
  plugins: [VectorCodecPlugin],
};

After adding: embedding: number[] | null appears in all generated types, mutations accept Vector scalar, and SQL functions with vector args are surfaced in GraphQL.

---

Common Pitfalls

Issue	Cause	Fix
embedding field missing from schema	vector type not recognized	Add VectorCodecPlugin (or ConstructivePreset)
Unknown type "Vector" in codegen	Scalar not mapped	Add scalars: { Vector: 'number[]' } to codegen config
SQL function with vector arg not surfaced	Same as above	VectorCodecPlugin must be present
VectorMetricEnum duplicate type error	Multiple PgVectorPreset instances	Create the enum once outside the loop or deduplicate by name
withPgClient not in context	Missing makePgService in preset	Ensure pgServices is configured in your PostGraphile preset
getResource returning null in init hook	Table not in schemas list	Add the schema to schemas in getConnections or PostGraphile config
dimension mismatch error from pgvector	Query vector length ≠ column dimension	Set maxQueryDim in collection config; validate before calling

---

References

• Related skill: pgvector-setup — DB schema with HNSW indexes
• Related skill: pgvector-embeddings — generating and storing embeddings
• Related skill: rag-pipeline — full RAG pipeline from embed to LLM
• Related skill: agentic-kit-rag — wiring RAG into agentic-kit chat routes
• pgvector docs
• PostGraphile v5 plugin guide
• Grafast step plan API