@prisma-next/extension-pgvector 0.5.0-dev.9 → 0.6.0-dev.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +23 -6
- package/dist/codec-types-CQubO6uQ.d.mts +63 -0
- package/dist/codec-types-CQubO6uQ.d.mts.map +1 -0
- package/dist/codec-types.d.mts +1 -1
- package/dist/codec-types.mjs +1 -1
- package/dist/column-types.d.mts +2 -5
- package/dist/column-types.d.mts.map +1 -1
- package/dist/column-types.mjs +4 -7
- package/dist/column-types.mjs.map +1 -1
- package/dist/{constants-Co5golCK.mjs → constants-DX-00vYk.mjs} +2 -2
- package/dist/{constants-Co5golCK.mjs.map → constants-DX-00vYk.mjs.map} +1 -1
- package/dist/control.d.mts.map +1 -1
- package/dist/control.mjs +163 -30
- package/dist/control.mjs.map +1 -1
- package/dist/descriptor-meta-DEgJjLLi.mjs +178 -0
- package/dist/descriptor-meta-DEgJjLLi.mjs.map +1 -0
- package/dist/operation-types-Bd-jkNN3.d.mts +38 -0
- package/dist/operation-types-Bd-jkNN3.d.mts.map +1 -0
- package/dist/operation-types.d.mts +2 -76
- package/dist/operation-types.mjs +1 -1
- package/dist/pack.d.mts +3 -10
- package/dist/pack.d.mts.map +1 -1
- package/dist/pack.mjs +2 -3
- package/dist/runtime.d.mts +10 -1
- package/dist/runtime.d.mts.map +1 -1
- package/dist/runtime.mjs +6 -25
- package/dist/runtime.mjs.map +1 -1
- package/package.json +32 -17
- package/src/contract.d.ts +91 -0
- package/src/contract.json +40 -0
- package/src/contract.ts +67 -0
- package/src/core/codecs.ts +127 -59
- package/src/core/contract-space-constants.ts +30 -0
- package/src/core/descriptor-meta.ts +40 -36
- package/src/core/registry.ts +11 -0
- package/src/exports/column-types.ts +3 -6
- package/src/exports/control.ts +56 -35
- package/src/exports/operation-types.ts +1 -1
- package/src/exports/runtime.ts +11 -41
- package/src/types/operation-types.ts +19 -36
- package/dist/codec-types-BifaP625.d.mts +0 -27
- package/dist/codec-types-BifaP625.d.mts.map +0 -1
- package/dist/descriptor-meta-BQbvJJxu.mjs +0 -148
- package/dist/descriptor-meta-BQbvJJxu.mjs.map +0 -1
- package/dist/operation-types.d.mts.map +0 -1
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": "1",
|
|
3
|
+
"targetFamily": "sql",
|
|
4
|
+
"target": "postgres",
|
|
5
|
+
"profileHash": "sha256:1a8dbe044289f30a1de958fe800cc5a8378b285d2e126a8c44b58864bac2c18e",
|
|
6
|
+
"roots": {},
|
|
7
|
+
"models": {},
|
|
8
|
+
"storage": {
|
|
9
|
+
"storageHash": "sha256:382dae5bb1548e62cbc449530ea08a9ce0a0dbb280401e9588642223f33783ae",
|
|
10
|
+
"tables": {},
|
|
11
|
+
"types": {
|
|
12
|
+
"vector": {
|
|
13
|
+
"codecId": "pg/vector@1",
|
|
14
|
+
"nativeType": "vector",
|
|
15
|
+
"typeParams": {}
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
},
|
|
19
|
+
"capabilities": {
|
|
20
|
+
"postgres": {
|
|
21
|
+
"jsonAgg": true,
|
|
22
|
+
"lateral": true,
|
|
23
|
+
"limit": true,
|
|
24
|
+
"orderBy": true,
|
|
25
|
+
"returning": true
|
|
26
|
+
},
|
|
27
|
+
"sql": {
|
|
28
|
+
"defaultInInsert": true,
|
|
29
|
+
"enums": true,
|
|
30
|
+
"returning": true
|
|
31
|
+
}
|
|
32
|
+
},
|
|
33
|
+
"extensionPacks": {},
|
|
34
|
+
"meta": {},
|
|
35
|
+
"_generated": {
|
|
36
|
+
"warning": "⚠️ GENERATED FILE - DO NOT EDIT",
|
|
37
|
+
"message": "This file is automatically generated by \"prisma-next contract emit\".",
|
|
38
|
+
"regenerate": "To regenerate, run: prisma-next contract emit"
|
|
39
|
+
}
|
|
40
|
+
}
|
package/src/contract.ts
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* TS contract source for the `extension-pgvector` package.
|
|
3
|
+
*
|
|
4
|
+
* Authored against the contract-space package layout convention. The
|
|
5
|
+
* same emit pipeline application authors use is applied here:
|
|
6
|
+
*
|
|
7
|
+
* `prisma-next contract emit` → `<package>/src/contract.{json,d.ts}`
|
|
8
|
+
* `prisma-next migration plan` → `<package>/migrations/<dirName>/`
|
|
9
|
+
*
|
|
10
|
+
* The descriptor at `src/exports/control.ts` then wires the emitted
|
|
11
|
+
* JSON artefacts via JSON-import declarations.
|
|
12
|
+
*
|
|
13
|
+
* ## IR coverage
|
|
14
|
+
*
|
|
15
|
+
* pgvector ships **no tables** of its own. The single object the
|
|
16
|
+
* extension contributes to the contract IR is the parameterised native
|
|
17
|
+
* type `vector(N)`, registered under `storage.types`. Per-column
|
|
18
|
+
* instances on the user's side carry concrete `typeParams.length`
|
|
19
|
+
* (e.g. `vector(1536)`); the registration here declares the
|
|
20
|
+
* parameterised shape so the verifier sees `vector` as part of
|
|
21
|
+
* pgvector's space contribution and so the pinned `contract.json` on
|
|
22
|
+
* disk is materially distinct from an empty space.
|
|
23
|
+
*
|
|
24
|
+
* Unlike CipherStash's deferred typed objects (composite types /
|
|
25
|
+
* domains / enums — IR vocabulary deferral, see
|
|
26
|
+
* `packages/3-extensions/cipherstash/src/contract.prisma`),
|
|
27
|
+
* pgvector's `vector` IS representable in today's IR via
|
|
28
|
+
* {@link StorageTypeInstance}.
|
|
29
|
+
*
|
|
30
|
+
* ## Why TS, not PSL
|
|
31
|
+
*
|
|
32
|
+
* The contract-space package layout convention prefers PSL
|
|
33
|
+
* (`src/contract.prisma`). pgvector is the narrow exception called out
|
|
34
|
+
* in the convention: PSL's `types {}` block instantiates parameterised
|
|
35
|
+
* types at app authoring time (`Vector1536 = pgvector.Vector(1536)`)
|
|
36
|
+
* but has no surface for an extension to register the parameterised
|
|
37
|
+
* BASE type itself (the `storage.types.vector` entry with empty
|
|
38
|
+
* `typeParams` shown below). Until PSL grows that surface, this
|
|
39
|
+
* extension keeps its contract source in TS.
|
|
40
|
+
*
|
|
41
|
+
* @see docs/architecture docs/adrs/ADR 212 - Contract spaces.md
|
|
42
|
+
*/
|
|
43
|
+
|
|
44
|
+
import sqlFamily from '@prisma-next/family-sql/pack';
|
|
45
|
+
import { defineContract } from '@prisma-next/sql-contract-ts/contract-builder';
|
|
46
|
+
import postgresPack from '@prisma-next/target-postgres/pack';
|
|
47
|
+
import { VECTOR_CODEC_ID } from './core/constants';
|
|
48
|
+
import { PGVECTOR_NATIVE_TYPE } from './core/contract-space-constants';
|
|
49
|
+
|
|
50
|
+
export const contract = defineContract(
|
|
51
|
+
{
|
|
52
|
+
family: sqlFamily,
|
|
53
|
+
target: postgresPack,
|
|
54
|
+
},
|
|
55
|
+
() => ({
|
|
56
|
+
types: {
|
|
57
|
+
[PGVECTOR_NATIVE_TYPE]: {
|
|
58
|
+
codecId: VECTOR_CODEC_ID,
|
|
59
|
+
nativeType: PGVECTOR_NATIVE_TYPE,
|
|
60
|
+
typeParams: {},
|
|
61
|
+
},
|
|
62
|
+
},
|
|
63
|
+
models: {},
|
|
64
|
+
}),
|
|
65
|
+
);
|
|
66
|
+
|
|
67
|
+
export default contract;
|
package/src/core/codecs.ts
CHANGED
|
@@ -1,77 +1,145 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* pgvector extension codec.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
4
|
+
* Mirrors the patterns in `postgres/codecs-class.ts` and `sqlite/codecs-class.ts` for the single `pg/vector@1` codec. Three artifacts:
|
|
5
|
+
*
|
|
6
|
+
* 1. `PgVectorCodec` extends {@link CodecImpl} with the runtime encode/decode/encodeJson/decodeJson conversions inline. Conversions are simple enough (PostgreSQL `[1,2,3]` text format) that no shared helper module is warranted; the class body is the source of truth.
|
|
7
|
+
* 2. `PgVectorDescriptor` extends {@link CodecDescriptorImpl} with the codec id, traits, target types, params schema (`{ length: number }`, validated against {@link VECTOR_MAX_DIM}), `meta` (postgres `nativeType: 'vector'`), and the emit-path `renderOutputType` producing `Vector<${length}>`.
|
|
8
|
+
* 3. `pgVectorColumn(length)` per-codec column helper invoking `descriptor.factory({ length })` directly + passing the bare `nativeType: 'vector'`. The family-layer {@link expandNativeType} hook renders the parameterized form (`vector(1536)`) at emit/verify time from `nativeType` + `typeParams`.
|
|
9
|
+
*
|
|
10
|
+
* `length` threads into the runtime codec via the constructor so encode/decode/encodeJson/decodeJson enforce the declared dimension at every ingress path. Without this, `vector(3)` and `vector(1536)` would produce codecs with identical behaviour and a dimension-mismatched value would round-trip undetected.
|
|
6
11
|
*/
|
|
7
12
|
|
|
8
|
-
import {
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
13
|
+
import type { JsonValue } from '@prisma-next/contract/types';
|
|
14
|
+
import {
|
|
15
|
+
type AnyCodecDescriptor,
|
|
16
|
+
type CodecCallContext,
|
|
17
|
+
CodecDescriptorImpl,
|
|
18
|
+
CodecImpl,
|
|
19
|
+
type CodecInstanceContext,
|
|
20
|
+
type ColumnHelperFor,
|
|
21
|
+
type ColumnHelperForStrict,
|
|
22
|
+
column,
|
|
23
|
+
} from '@prisma-next/framework-components/codec';
|
|
24
|
+
import type { ExtractCodecTypes } from '@prisma-next/sql-relational-core/ast';
|
|
25
|
+
import type { StandardSchemaV1 } from '@standard-schema/spec';
|
|
26
|
+
import { type as arktype } from 'arktype';
|
|
27
|
+
import { VECTOR_CODEC_ID, VECTOR_MAX_DIM } from './constants';
|
|
28
|
+
|
|
29
|
+
type VectorParams = { readonly length: number };
|
|
30
|
+
|
|
31
|
+
const vectorParamsSchema = arktype({
|
|
32
|
+
length: 'number',
|
|
33
|
+
}).narrow((params, ctx) => {
|
|
34
|
+
const { length } = params;
|
|
35
|
+
if (!Number.isInteger(length)) {
|
|
36
|
+
return ctx.mustBe('an integer');
|
|
37
|
+
}
|
|
38
|
+
if (length < 1 || length > VECTOR_MAX_DIM) {
|
|
39
|
+
return ctx.mustBe(`in the range [1, ${VECTOR_MAX_DIM}]`);
|
|
40
|
+
}
|
|
41
|
+
return true;
|
|
42
|
+
}) satisfies StandardSchemaV1<VectorParams>;
|
|
43
|
+
|
|
44
|
+
const PG_VECTOR_META = { db: { sql: { postgres: { nativeType: 'vector' } } } } as const;
|
|
45
|
+
|
|
46
|
+
export class PgVectorCodec extends CodecImpl<
|
|
47
|
+
typeof VECTOR_CODEC_ID,
|
|
48
|
+
readonly ['equality'],
|
|
49
|
+
string,
|
|
50
|
+
number[]
|
|
51
|
+
> {
|
|
52
|
+
readonly length: number | undefined;
|
|
53
|
+
|
|
54
|
+
constructor(descriptor: AnyCodecDescriptor, length: number | undefined) {
|
|
55
|
+
super(descriptor);
|
|
56
|
+
this.length = length;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
assertVector(value: unknown): asserts value is number[] {
|
|
26
60
|
if (!Array.isArray(value)) {
|
|
27
61
|
throw new Error('Vector value must be an array of numbers');
|
|
28
62
|
}
|
|
29
63
|
if (!value.every((v) => typeof v === 'number')) {
|
|
30
64
|
throw new Error('Vector value must contain only numbers');
|
|
31
65
|
}
|
|
32
|
-
|
|
33
|
-
|
|
66
|
+
if (this.length !== undefined && value.length !== this.length) {
|
|
67
|
+
throw new Error(`Vector length mismatch: expected ${this.length}, got ${value.length}`);
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
async encode(value: number[], _ctx: CodecCallContext): Promise<string> {
|
|
72
|
+
this.assertVector(value);
|
|
34
73
|
return `[${value.join(',')}]`;
|
|
35
|
-
}
|
|
36
|
-
|
|
37
|
-
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
async decode(wire: string, _ctx: CodecCallContext): Promise<number[]> {
|
|
38
77
|
if (typeof wire !== 'string') {
|
|
39
78
|
throw new Error('Vector wire value must be a string');
|
|
40
79
|
}
|
|
41
|
-
// Parse PostgreSQL vector format: [1,2,3]
|
|
42
80
|
if (!wire.startsWith('[') || !wire.endsWith(']')) {
|
|
43
81
|
throw new Error(`Invalid vector format: expected "[...]", got "${wire}"`);
|
|
44
82
|
}
|
|
45
83
|
const content = wire.slice(1, -1).trim();
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
84
|
+
const parsed =
|
|
85
|
+
content === ''
|
|
86
|
+
? []
|
|
87
|
+
: content.split(',').map((v) => {
|
|
88
|
+
const num = Number.parseFloat(v.trim());
|
|
89
|
+
if (Number.isNaN(num)) {
|
|
90
|
+
throw new Error(`Invalid vector value: "${v}" is not a number`);
|
|
91
|
+
}
|
|
92
|
+
return num;
|
|
93
|
+
});
|
|
94
|
+
this.assertVector(parsed);
|
|
95
|
+
return parsed;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
encodeJson(value: number[]): JsonValue {
|
|
99
|
+
this.assertVector(value);
|
|
100
|
+
return value;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
decodeJson(json: JsonValue): number[] {
|
|
104
|
+
this.assertVector(json);
|
|
105
|
+
return json;
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
export class PgVectorDescriptor extends CodecDescriptorImpl<VectorParams> {
|
|
110
|
+
override readonly codecId = VECTOR_CODEC_ID;
|
|
111
|
+
override readonly traits = ['equality'] as const;
|
|
112
|
+
override readonly targetTypes = ['vector'] as const;
|
|
113
|
+
override readonly meta = PG_VECTOR_META;
|
|
114
|
+
override readonly paramsSchema: StandardSchemaV1<VectorParams> = vectorParamsSchema;
|
|
115
|
+
override renderOutputType(params: VectorParams): string {
|
|
116
|
+
return `Vector<${params.length}>`;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* The runtime calls `factory(undefined)(ctx)` to materialize a representative codec for parameterized descriptors that ship a no-params column variant (here, `vectorColumn` vs `vector(N)`). The runtime cast widens `params` to `unknown`, so guarding with an optional read keeps the typed call site (`factory({ length })`) strict while still producing a length-agnostic codec for representative use. Encode/decode for an undimensioned column run through this representative; the wire format `[v1,v2,...]` is dimension-independent.
|
|
120
|
+
*/
|
|
121
|
+
override factory(params: VectorParams): (ctx: CodecInstanceContext) => PgVectorCodec {
|
|
122
|
+
return () => new PgVectorCodec(this, (params as VectorParams | undefined)?.length);
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
export const pgVectorDescriptor = new PgVectorDescriptor();
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* Per-codec column helper for `pg/vector@1`. Generic over `N extends number` so the column site preserves the dimension literal in `typeParams` (e.g. `pgVectorColumn(1536)` packs `typeParams: { length: 1536 }`).
|
|
130
|
+
*
|
|
131
|
+
* Passes the bare `nativeType: 'vector'`; the family-layer `expandNativeType` hook renders the parameterized form (`vector(1536)`) at emit/verify time from `nativeType` + `typeParams`.
|
|
132
|
+
*/
|
|
133
|
+
export const pgVectorColumn = <N extends number>(length: N) =>
|
|
134
|
+
column(pgVectorDescriptor.factory({ length }), pgVectorDescriptor.codecId, { length }, 'vector');
|
|
135
|
+
|
|
136
|
+
pgVectorColumn satisfies ColumnHelperFor<PgVectorDescriptor>;
|
|
137
|
+
pgVectorColumn satisfies ColumnHelperForStrict<PgVectorDescriptor>;
|
|
138
|
+
|
|
139
|
+
const codecDescriptorMap = {
|
|
140
|
+
vector: pgVectorDescriptor,
|
|
141
|
+
} as const;
|
|
142
|
+
|
|
143
|
+
export type CodecTypes = ExtractCodecTypes<typeof codecDescriptorMap>;
|
|
144
|
+
|
|
145
|
+
export const codecDescriptors: readonly AnyCodecDescriptor[] = Object.values(codecDescriptorMap);
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Static names and identifiers used across pgvector's contract space.
|
|
3
|
+
*
|
|
4
|
+
* Centralised here so the contract IR (`./contract`), the baseline
|
|
5
|
+
* migration ops (`./migrations`), the head ref, and the descriptor
|
|
6
|
+
* (`../exports/control`) all reference the same values without typos.
|
|
7
|
+
*
|
|
8
|
+
* The space identifier `'pgvector'` is what the framework writes to
|
|
9
|
+
* `migrations/` in the user's repo and what the marker table's
|
|
10
|
+
* `space` column carries for pgvector-owned rows.
|
|
11
|
+
*
|
|
12
|
+
* The `pgvector:*` invariantId namespace is locked here — once
|
|
13
|
+
* published, an invariantId is immutable so downstream consumers can
|
|
14
|
+
* reference it by literal string match.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
export const PGVECTOR_SPACE_ID = 'pgvector' as const;
|
|
18
|
+
|
|
19
|
+
export const PGVECTOR_NATIVE_TYPE = 'vector' as const;
|
|
20
|
+
|
|
21
|
+
export const PGVECTOR_BASELINE_MIGRATION_NAME = '20260601T0000_install_vector_extension' as const;
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* `pgvector:*` invariantIds emitted by the baseline migration. Each id,
|
|
25
|
+
* once published, is immutable: downstream consumers (other extensions,
|
|
26
|
+
* the marker table) reference them by literal string match.
|
|
27
|
+
*/
|
|
28
|
+
export const PGVECTOR_INVARIANTS = {
|
|
29
|
+
installVector: 'pgvector:install-vector-v1',
|
|
30
|
+
} as const;
|
|
@@ -1,38 +1,49 @@
|
|
|
1
|
-
import
|
|
1
|
+
import { buildOperation, refsOf, toExpr } from '@prisma-next/sql-relational-core/expression';
|
|
2
2
|
import type { CodecTypes } from '../types/codec-types';
|
|
3
|
+
import type { QueryOperationTypes } from '../types/operation-types';
|
|
3
4
|
import { pgvectorAuthoringTypes } from './authoring';
|
|
4
|
-
import {
|
|
5
|
+
import { pgvectorCodecRegistry } from './registry';
|
|
5
6
|
|
|
6
7
|
const pgvectorTypeId = 'pg/vector@1' as const;
|
|
7
8
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
{ codecId: pgvectorTypeId
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
9
|
+
type CodecTypesBase = Record<string, { readonly input: unknown; readonly output: unknown }>;
|
|
10
|
+
|
|
11
|
+
export function pgvectorQueryOperations<CT extends CodecTypesBase>(): QueryOperationTypes<CT> {
|
|
12
|
+
return {
|
|
13
|
+
cosineDistance: {
|
|
14
|
+
self: { codecId: pgvectorTypeId },
|
|
15
|
+
impl: (self, other) => {
|
|
16
|
+
const selfRefs = refsOf(self);
|
|
17
|
+
return buildOperation({
|
|
18
|
+
method: 'cosineDistance',
|
|
19
|
+
args: [toExpr(self, pgvectorTypeId, selfRefs), toExpr(other, pgvectorTypeId, selfRefs)],
|
|
20
|
+
returns: { codecId: 'pg/float8@1', nullable: false },
|
|
21
|
+
lowering: {
|
|
22
|
+
targetFamily: 'sql',
|
|
23
|
+
strategy: 'function',
|
|
24
|
+
template: '{{self}} <=> {{arg0}}',
|
|
25
|
+
},
|
|
26
|
+
});
|
|
27
|
+
},
|
|
20
28
|
},
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
29
|
+
cosineSimilarity: {
|
|
30
|
+
self: { codecId: pgvectorTypeId },
|
|
31
|
+
impl: (self, other) => {
|
|
32
|
+
const selfRefs = refsOf(self);
|
|
33
|
+
return buildOperation({
|
|
34
|
+
method: 'cosineSimilarity',
|
|
35
|
+
args: [toExpr(self, pgvectorTypeId, selfRefs), toExpr(other, pgvectorTypeId, selfRefs)],
|
|
36
|
+
returns: { codecId: 'pg/float8@1', nullable: false },
|
|
37
|
+
lowering: {
|
|
38
|
+
targetFamily: 'sql',
|
|
39
|
+
strategy: 'function',
|
|
40
|
+
template: '1 - ({{self}} <=> {{arg0}})',
|
|
41
|
+
},
|
|
42
|
+
});
|
|
43
|
+
},
|
|
33
44
|
},
|
|
34
|
-
}
|
|
35
|
-
|
|
45
|
+
};
|
|
46
|
+
}
|
|
36
47
|
|
|
37
48
|
const pgvectorPackMetaBase = {
|
|
38
49
|
kind: 'extension',
|
|
@@ -50,7 +61,7 @@ const pgvectorPackMetaBase = {
|
|
|
50
61
|
},
|
|
51
62
|
types: {
|
|
52
63
|
codecTypes: {
|
|
53
|
-
|
|
64
|
+
codecDescriptors: Array.from(pgvectorCodecRegistry.values()),
|
|
54
65
|
import: {
|
|
55
66
|
package: '@prisma-next/extension-pgvector/codec-types',
|
|
56
67
|
named: 'CodecTypes',
|
|
@@ -64,13 +75,6 @@ const pgvectorPackMetaBase = {
|
|
|
64
75
|
},
|
|
65
76
|
],
|
|
66
77
|
},
|
|
67
|
-
operationTypes: {
|
|
68
|
-
import: {
|
|
69
|
-
package: '@prisma-next/extension-pgvector/operation-types',
|
|
70
|
-
named: 'OperationTypes',
|
|
71
|
-
alias: 'PgVectorOperationTypes',
|
|
72
|
-
},
|
|
73
|
-
},
|
|
74
78
|
queryOperationTypes: {
|
|
75
79
|
import: {
|
|
76
80
|
package: '@prisma-next/extension-pgvector/operation-types',
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { buildCodecDescriptorRegistry } from '@prisma-next/sql-relational-core/codec-descriptor-registry';
|
|
2
|
+
import type { CodecDescriptorRegistry } from '@prisma-next/sql-relational-core/query-lane-context';
|
|
3
|
+
import { codecDescriptors } from './codecs';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Registry of every codec descriptor shipped by `@prisma-next/extension-pgvector`.
|
|
7
|
+
*
|
|
8
|
+
* Public consumer surface for the pgvector codec set. Currently a single entry (`pg/vector@1`); the registry shape stays consistent with the other codec-shipping packages so consumers don't need to special-case extensions. See ADR 208.
|
|
9
|
+
*/
|
|
10
|
+
export const pgvectorCodecRegistry: CodecDescriptorRegistry =
|
|
11
|
+
buildCodecDescriptorRegistry(codecDescriptors);
|
|
@@ -1,16 +1,14 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Column type descriptors for pgvector extension.
|
|
3
3
|
*
|
|
4
|
-
* These descriptors provide both codecId and nativeType for use in contract authoring.
|
|
5
|
-
* They are derived from the same source of truth as codec definitions and manifests.
|
|
4
|
+
* These descriptors provide both codecId and nativeType for use in contract authoring. They are derived from the same source of truth as codec definitions and manifests.
|
|
6
5
|
*/
|
|
7
6
|
|
|
8
|
-
import type { ColumnTypeDescriptor } from '@prisma-next/
|
|
7
|
+
import type { ColumnTypeDescriptor } from '@prisma-next/framework-components/codec';
|
|
9
8
|
import { VECTOR_CODEC_ID, VECTOR_MAX_DIM } from '../core/constants';
|
|
10
9
|
|
|
11
10
|
/**
|
|
12
|
-
* Static vector column descriptor without dimension.
|
|
13
|
-
* Use `vector(N)` for dimensioned vectors that produce `vector(N)` DDL.
|
|
11
|
+
* Static vector column descriptor without dimension. Use `vector(N)` for dimensioned vectors that produce `vector(N)` DDL.
|
|
14
12
|
*/
|
|
15
13
|
export const vectorColumn = {
|
|
16
14
|
codecId: VECTOR_CODEC_ID,
|
|
@@ -25,7 +23,6 @@ export const vectorColumn = {
|
|
|
25
23
|
* .column('embedding', { type: vector(1536), nullable: false })
|
|
26
24
|
* // Produces: nativeType: 'vector', typeParams: { length: 1536 }
|
|
27
25
|
* ```
|
|
28
|
-
*
|
|
29
26
|
* @param length - The dimension of the vector (e.g., 1536 for OpenAI embeddings)
|
|
30
27
|
* @returns A column type descriptor with `typeParams.length` set
|
|
31
28
|
* @throws {RangeError} If length is not an integer in the range [1, VECTOR_MAX_DIM]
|
package/src/exports/control.ts
CHANGED
|
@@ -1,11 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Control-plane descriptor for the pgvector extension.
|
|
3
|
+
*
|
|
4
|
+
* **Contract-space package layout.** The extension's contract
|
|
5
|
+
* + migrations are emitted by the same pipeline application authors use:
|
|
6
|
+
*
|
|
7
|
+
* `prisma-next contract emit` → `<package>/src/contract.{json,d.ts}`
|
|
8
|
+
* `prisma-next migration plan` → `<package>/migrations/<dir>/...`
|
|
9
|
+
*
|
|
10
|
+
* The descriptor wires those JSON artefacts via JSON-import declarations
|
|
11
|
+
* so they flow through the consuming application's module resolver
|
|
12
|
+
* without filesystem assumptions, and synthesises the canonical
|
|
13
|
+
* {@link import('@prisma-next/framework-components/control').MigrationPackage}
|
|
14
|
+
* shape for the framework's runner / verifier to consume. Readers in
|
|
15
|
+
* `@prisma-next/migration-tools` add `dirPath` when loading from disk
|
|
16
|
+
* (`OnDiskMigrationPackage`); descriptor-bundled packages do not need
|
|
17
|
+
* it because the framework reads them directly from the descriptor.
|
|
18
|
+
*
|
|
19
|
+
* Wired surfaces:
|
|
20
|
+
*
|
|
21
|
+
* - `contractSpace.{contractJson,migrations,headRef}` — sourced from
|
|
22
|
+
* the on-disk artefacts emitted by `build:contract-space`.
|
|
23
|
+
* - `types.codecTypes.controlPlaneHooks[PGVECTOR_CODEC_ID]` — codec
|
|
24
|
+
* control hooks (`expandNativeType`, `resolveIdentityValue`) the
|
|
25
|
+
* SQL planner extracts via `extractCodecControlHooks` and uses to
|
|
26
|
+
* render `vector(N)` column types and the canonical zero-vector
|
|
27
|
+
* identity literal.
|
|
28
|
+
*
|
|
29
|
+
* @see docs/architecture docs/adrs/ADR 212 - Contract spaces.md
|
|
30
|
+
* (contract-space package layout convention).
|
|
31
|
+
*/
|
|
32
|
+
|
|
33
|
+
import type { Contract } from '@prisma-next/contract/types';
|
|
1
34
|
import type {
|
|
2
35
|
CodecControlHooks,
|
|
3
|
-
ComponentDatabaseDependencies,
|
|
4
36
|
SqlControlExtensionDescriptor,
|
|
5
37
|
} from '@prisma-next/family-sql/control';
|
|
38
|
+
import { contractSpaceFromJson } from '@prisma-next/migration-tools/spaces';
|
|
39
|
+
import type { SqlStorage } from '@prisma-next/sql-contract/types';
|
|
40
|
+
import baselineMetadata from '../../migrations/20260601T0000_install_vector_extension/migration.json' with {
|
|
41
|
+
type: 'json',
|
|
42
|
+
};
|
|
43
|
+
import baselineOps from '../../migrations/20260601T0000_install_vector_extension/ops.json' with {
|
|
44
|
+
type: 'json',
|
|
45
|
+
};
|
|
46
|
+
import headRef from '../../migrations/refs/head.json' with { type: 'json' };
|
|
47
|
+
import contractJson from '../contract.json' with { type: 'json' };
|
|
48
|
+
import { PGVECTOR_SPACE_ID } from '../core/contract-space-constants';
|
|
6
49
|
import { pgvectorPackMeta, pgvectorQueryOperations } from '../core/descriptor-meta';
|
|
7
50
|
|
|
8
51
|
const PGVECTOR_CODEC_ID = 'pg/vector@1' as const;
|
|
52
|
+
const BASELINE_DIR_NAME = '20260601T0000_install_vector_extension';
|
|
9
53
|
|
|
10
54
|
function buildVectorIdentityValue(typeParams: Record<string, unknown> | undefined): string | null {
|
|
11
55
|
const length = typeParams?.['length'];
|
|
@@ -28,44 +72,22 @@ const vectorControlPlaneHooks: CodecControlHooks = {
|
|
|
28
72
|
resolveIdentityValue: ({ typeParams }) => buildVectorIdentityValue(typeParams),
|
|
29
73
|
};
|
|
30
74
|
|
|
31
|
-
const
|
|
32
|
-
|
|
75
|
+
const pgvectorContractSpace = contractSpaceFromJson<Contract<SqlStorage>>({
|
|
76
|
+
contractJson,
|
|
77
|
+
migrations: [
|
|
33
78
|
{
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
{
|
|
38
|
-
id: 'extension.vector',
|
|
39
|
-
label: 'Enable extension "vector"',
|
|
40
|
-
summary: 'Ensures the vector extension is available for pgvector operations',
|
|
41
|
-
operationClass: 'additive',
|
|
42
|
-
target: { id: 'postgres' },
|
|
43
|
-
precheck: [
|
|
44
|
-
{
|
|
45
|
-
description: 'verify extension "vector" is not already enabled',
|
|
46
|
-
sql: "SELECT NOT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'vector')",
|
|
47
|
-
},
|
|
48
|
-
],
|
|
49
|
-
execute: [
|
|
50
|
-
{
|
|
51
|
-
description: 'create extension "vector"',
|
|
52
|
-
sql: 'CREATE EXTENSION IF NOT EXISTS vector',
|
|
53
|
-
},
|
|
54
|
-
],
|
|
55
|
-
postcheck: [
|
|
56
|
-
{
|
|
57
|
-
description: 'confirm extension "vector" is enabled',
|
|
58
|
-
sql: "SELECT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'vector')",
|
|
59
|
-
},
|
|
60
|
-
],
|
|
61
|
-
},
|
|
62
|
-
],
|
|
79
|
+
dirName: BASELINE_DIR_NAME,
|
|
80
|
+
metadata: baselineMetadata,
|
|
81
|
+
ops: baselineOps,
|
|
63
82
|
},
|
|
64
83
|
],
|
|
65
|
-
|
|
84
|
+
headRef,
|
|
85
|
+
});
|
|
66
86
|
|
|
67
87
|
const pgvectorExtensionDescriptor: SqlControlExtensionDescriptor<'postgres'> = {
|
|
68
88
|
...pgvectorPackMeta,
|
|
89
|
+
id: PGVECTOR_SPACE_ID,
|
|
90
|
+
contractSpace: pgvectorContractSpace,
|
|
69
91
|
types: {
|
|
70
92
|
...pgvectorPackMeta.types,
|
|
71
93
|
codecTypes: {
|
|
@@ -75,8 +97,7 @@ const pgvectorExtensionDescriptor: SqlControlExtensionDescriptor<'postgres'> = {
|
|
|
75
97
|
},
|
|
76
98
|
},
|
|
77
99
|
},
|
|
78
|
-
queryOperations: () => pgvectorQueryOperations,
|
|
79
|
-
databaseDependencies: pgvectorDatabaseDependencies,
|
|
100
|
+
queryOperations: () => pgvectorQueryOperations(),
|
|
80
101
|
create: () => ({
|
|
81
102
|
familyId: 'sql' as const,
|
|
82
103
|
targetId: 'postgres' as const,
|