feat: add paradedb-named aliases for bm25-named API (paradedb/paradedb#5706)

Author: rebasedming

paradedb-demo/README.md

@@ -13,7 +13,7 @@ Exercises:
 - `CREATE EXTENSION pg_search` / `vector` via the docker init scripts (`init/*.sql`).
 - Automatic `CREATE INDEX ... USING bm25 (...) WITH (key_field='...')` via upstream's index-type registry. The contract uses `type: 'bm25'` so the migration also runs on released servers (<= 0.24.3); on pg_search 0.25.0+ (unreleased) `type: 'paradedb'` emits `USING paradedb`, the primary access method name. The gated test in `test/bm25.integration.test.ts` exercises the `paradedb` AM when the server registers it.
 
-The index covers the text columns only: released pg_search builds reject vector columns in ParadeDB indexes (requires pg_search 0.25.0+, unreleased; paradedb/paradedb#5685), so vector Top-K runs unaccelerated here. The gated integration test in `test/vector.integration.test.ts` probes which access method carries the vector opclasses, exercises the vector-in-index DDL (via `renderBm25IndexDdl`) against it, and skips with a clear reason on released builds.
+The index covers the text columns only: released pg_search builds reject vector columns in ParadeDB indexes (requires pg_search 0.25.0+, unreleased; paradedb/paradedb#5685), so vector Top-K runs unaccelerated here. The gated integration test in `test/vector.integration.test.ts` probes which access method carries the vector opclasses, exercises the vector-in-index DDL (via `renderParadeDbIndexDdl`) against it, and skips with a clear reason on released builds.
 
 ## Run it
 

paradedb-demo/test/vector.integration.test.ts

@@ -1,5 +1,5 @@
 import 'dotenv/config';
-import { renderBm25IndexDdl } from '@prisma-next/extension-paradedb/ddl';
+import { renderParadeDbIndexDdl } from '@prisma-next/extension-paradedb/ddl';
 import pg from 'pg';
 import { beforeAll, describe, expect, it } from 'vitest';
 import { loadAppConfig } from '../src/app-config';
@@ -69,7 +69,7 @@ describe.skipIf(SKIP)('paradedb vector integration', () => {
       await client.query(
         `INSERT INTO public.vector_idx_probe VALUES (1, '[1,0,0]'), (2, '[0.1,0.9,0.1]'), (3, '[0,0,1]')`,
       );
-      const ddl = renderBm25IndexDdl({
+      const ddl = renderParadeDbIndexDdl({
         name: 'vector_idx_probe_idx',
         table: 'vector_idx_probe',
         schema: 'public',

paradedb/README.md

@@ -4,7 +4,7 @@ ParadeDB full-text and vector search extension pack for Prisma Next.
 
 ## Overview
 
-This extension pack registers `'paradedb'` and `'bm25'` index types with the SQL family's index-type registry, so contracts can author BM25 full-text search indexes via the standard `constraints.index(...)` surface and the Postgres adapter emits `CREATE INDEX ... USING paradedb WITH (...)` (or `USING bm25`) DDL. `paradedb` is the primary access method name on pg_search 0.25.0+ (unreleased); `bm25` is a permanent backwards-compatible alias and the only name on released servers (<= 0.24.3).
+This extension pack registers `'paradedb'` and `'bm25'` index types with the SQL family's index-type registry, so contracts can author BM25 full-text search indexes via the standard `constraints.index(...)` surface and the Postgres adapter emits `CREATE INDEX ... USING paradedb WITH (...)` (or `USING bm25`) DDL. `paradedb` is the primary access method name on pg_search 0.25.0+ (unreleased); `bm25` is a permanent backwards-compatible alias and the only name on released servers (<= 0.24.3). The DDL helper API is likewise also available under bm25 names (`renderBm25IndexDdl`, `Bm25IndexDdlOptions`, `Bm25VectorIndexColumn`).
 
 The v1 surface covers the `key_field` storage parameter only. Per-field tokenizer and column configuration is deferred to expression-index support.
 
@@ -15,7 +15,7 @@ It also provides native pgvector `vector(n)` column support (no pgvector ORM lib
 - **Index registration**: declares `'paradedb'` (primary) and `'bm25'` (alias) entries via `defineIndexTypes()` carrying an arktype validator for the options shape
 - **Vector columns**: `vectorColumn(dimensions)` maps to `vector(n)` DDL; the `paradedb/vector@1` codec serializes `number[]` ⇄ `'[1,2,3]'` in both directions
 - **Vector queries**: `paradeDbL2Distance` (`<->`), `paradeDbCosineDistance` (`<=>`), `paradeDbInnerProduct` (`<#>`), and `paradeDbAll` (`@@@ pdb.all()`)
-- **Vector index DDL**: `renderBm25IndexDdl(...)` renders `CREATE INDEX ... USING paradedb` (or `USING bm25` via the `am` option) statements with per-column vector opclasses for raw migrations
+- **Vector index DDL**: `renderParadeDbIndexDdl(...)` renders `CREATE INDEX ... USING paradedb` (or `USING bm25` via the `am` option) statements with per-column vector opclasses for raw migrations
 - **Extension descriptor**: declares the `paradedb/bm25` and `paradedb/vector` capabilities for contract-level feature detection
 - **Pack ref export**: ships a pure `/pack` entrypoint for TypeScript contract authoring
 
@@ -97,9 +97,9 @@ The column emits `vector(3)` DDL and reads/writes `number[]` values.
 Vector columns listed in a `constraints.index([...], { type: 'paradedb', ... })` declaration get the AM's default opclass, `vector_l2_ops` (L2). The contract index surface cannot express per-column opclasses yet, so for the cosine or inner-product metric render the DDL for a raw migration:
 
 ```typescript
-import { renderBm25IndexDdl } from '@prisma-next/extension-paradedb/ddl';
+import { renderParadeDbIndexDdl } from '@prisma-next/extension-paradedb/ddl';
 
-renderBm25IndexDdl({
+renderParadeDbIndexDdl({
   name: 'item_vector_idx',
   table: 'item',
   keyField: 'id',
@@ -147,7 +147,7 @@ The ORDER BY distance operator must match the index opclass metric; a mismatch d
 ## Not yet implemented
 
 - Per-column / per-expression tokenizer configuration (deferred to expression-index support)
-- Per-column vector opclasses in `constraints.index(...)` (use `renderBm25IndexDdl` meanwhile)
+- Per-column vector opclasses in `constraints.index(...)` (use `renderParadeDbIndexDdl` meanwhile)
 - `halfvec` / `sparsevec` column types
 - `CREATE EXTENSION pg_search` / `CREATE EXTENSION vector` via migration planner (removed with upstream's `databaseDependencies` hook; install the extensions before `db init`)
 - Aggregation and highlight functions

paradedb/src/core/bm25-index-ddl.ts

@@ -101,3 +101,8 @@ export function renderBm25IndexDdl(options: Bm25IndexDdlOptions): string {
       : `${quoteIdentifier(options.schema)}.${quoteIdentifier(options.table)}`;
   return `CREATE INDEX ${quoteIdentifier(options.name)} ON ${qualifiedTable} USING ${am} (${columnList}) WITH (key_field = '${escapeLiteral(options.keyField)}')`;
 }
+
+// Primary paradedb-named API; the bm25 names above remain supported aliases.
+export type ParadeDbVectorIndexColumn = Bm25VectorIndexColumn;
+export type ParadeDbIndexDdlOptions = Bm25IndexDdlOptions;
+export const renderParadeDbIndexDdl = renderBm25IndexDdl;

paradedb/src/exports/ddl.ts

@@ -1,8 +1,11 @@
 export {
   type Bm25IndexDdlOptions,
   type Bm25VectorIndexColumn,
+  type ParadeDbIndexDdlOptions,
+  type ParadeDbVectorIndexColumn,
   type VectorMetric,
   renderBm25IndexDdl,
+  renderParadeDbIndexDdl,
   VECTOR_DISTANCE_OPERATORS,
   VECTOR_OPCLASSES,
 } from '../core/bm25-index-ddl';

paradedb/test/vector.test.ts

@@ -1,6 +1,13 @@
 import { OperationExpr, ParamRef } from '@prisma-next/sql-relational-core/ast';
 import { describe, expect, it } from 'vitest';
-import { renderBm25IndexDdl, VECTOR_DISTANCE_OPERATORS, VECTOR_OPCLASSES } from '../src/exports/ddl';
+import {
+  type ParadeDbIndexDdlOptions,
+  type ParadeDbVectorIndexColumn,
+  renderBm25IndexDdl,
+  renderParadeDbIndexDdl,
+  VECTOR_DISTANCE_OPERATORS,
+  VECTOR_OPCLASSES,
+} from '../src/exports/ddl';
 import { paradedbPackMeta } from '../src/core/descriptor-meta';
 import {
   expandVectorNativeType,
@@ -151,6 +158,20 @@ describe('renderBm25IndexDdl', () => {
     );
   });
 
+  it('is also exported under the primary paradedb name', () => {
+    expect(renderParadeDbIndexDdl).toBe(renderBm25IndexDdl);
+    const embedding: ParadeDbVectorIndexColumn = { column: 'embedding', metric: 'cosine' };
+    const options: ParadeDbIndexDdlOptions = {
+      name: 'idx',
+      table: 'item',
+      keyField: 'id',
+      columns: ['id', embedding],
+    };
+    expect(renderParadeDbIndexDdl(options)).toBe(
+      'CREATE INDEX "idx" ON "item" USING paradedb ("id", "embedding" vector_cosine_ops) WITH (key_field = \'id\')',
+    );
+  });
+
   it('rejects unknown access methods', () => {
     expect(() =>
       renderBm25IndexDdl({