{"id":48618829,"url":"https://github.com/sudodevstudio/genkitx-supabase","last_synced_at":"2026-04-09T03:01:13.184Z","repository":{"id":349684649,"uuid":"1197984322","full_name":"SudoDevStudio/genkitx-supabase","owner":"SudoDevStudio","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-07T03:54:57.000Z","size":102,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-07T05:24:21.282Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SudoDevStudio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T03:06:49.000Z","updated_at":"2026-04-07T03:55:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SudoDevStudio/genkitx-supabase","commit_stats":null,"previous_names":["sudodevstudio/genkitx-supabase"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/SudoDevStudio/genkitx-supabase","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SudoDevStudio%2Fgenkitx-supabase","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SudoDevStudio%2Fgenkitx-supabase/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SudoDevStudio%2Fgenkitx-supabase/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SudoDevStudio%2Fgenkitx-supabase/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SudoDevStudio","download_url":"https://codeload.github.com/SudoDevStudio/genkitx-supabase/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SudoDevStudio%2Fgenkitx-supabase/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31583290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"online","status_checked_at":"2026-04-09T02:00:06.848Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-09T03:00:57.877Z","updated_at":"2026-04-09T03:01:13.177Z","avatar_url":"https://github.com/SudoDevStudio.png","language":"TypeScript","readme":"# @sudodevstudio/genkitx-supabase\n\n`@sudodevstudio/genkitx-supabase` is a Genkit community plugin that turns a Supabase Postgres + `pgvector` table into a Genkit indexer and retriever pair for RAG workflows.\n\nIf you want the short version first, see [`HOW_IT_WORKS.md`](./HOW_IT_WORKS.md).\n\nIt lets you keep embeddings, content, and JSONB metadata in Supabase while using the familiar Genkit flow:\n\n- configure a plugin with an `indexName` and embedder\n- index documents with `ai.index()`\n- retrieve relevant documents with `ai.retrieve()`\n- filter retrievals with JSONB metadata\n\n## Why Supabase + Genkit\n\nSupabase gives you managed Postgres, `pgvector`, and JSONB in one place. Genkit gives you a clean retrieval/indexing abstraction inside AI flows. Together, they make it easy to build RAG pipelines that stay close to your application data and use standard Postgres tooling.\n\n## Features\n\n- Genkit plugin UX modeled after existing vector-store integrations\n- `supabaseVectorStore(configs)`\n- `supabaseIndexerRef(indexName)`\n- `supabaseRetrieverRef(indexName)`\n- batch embedding and upsert indexing\n- delete by id through `ai.index()`\n- top-k semantic retrieval through a Supabase RPC function\n- JSONB metadata filtering\n- configurable schema, table, RPC, and column names\n- useful validation and runtime errors\n\n## Install\n\n```bash\nnpm install @sudodevstudio/genkitx-supabase @supabase/supabase-js genkit\n```\n\nIf you want to use the Google AI quickstart below:\n\n```bash\nnpm install @genkit-ai/google-genai\n```\n\n## Quickstart\n\n```ts\nimport { googleAI } from '@genkit-ai/google-genai';\nimport { Document, genkit } from 'genkit';\nimport {\n  supabaseIndexerRef,\n  supabaseRetrieverRef,\n  supabaseVectorStore,\n} from '@sudodevstudio/genkitx-supabase';\n\nconst ai = genkit({\n  plugins: [\n    googleAI(),\n    supabaseVectorStore([\n      {\n        indexName: 'docs',\n        embedder: googleAI.embedder('gemini-embedding-001'),\n        connection: {\n          url: process.env.SUPABASE_URL!,\n          key: process.env.SUPABASE_SERVICE_ROLE_KEY!,\n        },\n        embeddingDimension: 3072,\n      },\n    ]),\n  ],\n});\n\nconst docsIndexer = supabaseIndexerRef('docs');\nconst docsRetriever = supabaseRetrieverRef('docs');\n\nawait ai.index({\n  indexer: docsIndexer,\n  documents: [\n    Document.fromText('Supabase stores embeddings in Postgres.', {\n      id: 'doc-1',\n      topic: 'supabase',\n    }),\n  ],\n});\n\nconst docs = await ai.retrieve({\n  retriever: docsRetriever,\n  query: 'Where are the embeddings stored?',\n  options: { k: 3 },\n});\n```\n\n## SQL Setup\n\nThe package expects:\n\n- a pgvector-enabled table for documents\n- an RPC function that accepts `query_embedding`, `match_count`, and `filter`\n- rows containing your configured `id`, `content`, and `metadata` fields\n\nSQL examples are included in:\n\n- [`sql/001_create_rag_documents.sql`](./sql/001_create_rag_documents.sql)\n- [`sql/002_match_rag_documents.sql`](./sql/002_match_rag_documents.sql)\n\nDefault schema:\n\n- `id text primary key`\n- `content text not null`\n- `metadata jsonb not null default '{}'::jsonb`\n- `embedding extensions.vector(3072) not null`\n- `created_at timestamptz`\n- `updated_at timestamptz`\n\nIf your embedder uses a different dimension, update both the table definition and the RPC function signature to match.\n\n## Usage\n\n### Configure the plugin\n\n```ts\nimport { googleAI } from '@genkit-ai/google-genai';\nimport { genkit } from 'genkit';\nimport { supabaseVectorStore } from '@sudodevstudio/genkitx-supabase';\n\nconst ai = genkit({\n  plugins: [\n    googleAI(),\n    supabaseVectorStore([\n      {\n        indexName: 'products',\n        embedder: googleAI.embedder('gemini-embedding-001'),\n        connection: {\n          url: process.env.SUPABASE_URL!,\n          key: process.env.SUPABASE_SERVICE_ROLE_KEY!,\n        },\n        schema: 'public',\n        table: 'rag_documents',\n        queryRpcName: 'match_rag_documents',\n        idColumn: 'id',\n        contentColumn: 'content',\n        metadataColumn: 'metadata',\n        embeddingColumn: 'embedding',\n        defaultK: 5,\n        embeddingDimension: 3072,\n      },\n    ]),\n  ],\n});\n```\n\n### Index documents\n\nDocument ids are read from `document.metadata.id`. If a document already exists with the same id, it is updated.\n\n```ts\nimport { Document } from 'genkit';\nimport { supabaseIndexerRef } from '@sudodevstudio/genkitx-supabase';\n\nconst productsIndexer = supabaseIndexerRef('products');\n\nawait ai.index({\n  indexer: productsIndexer,\n  documents: [\n    Document.fromText('The red backpack fits a 16-inch laptop.', {\n      id: 'sku-red-backpack',\n      category: 'bags',\n      inventoryStatus: 'in_stock',\n    }),\n    Document.fromText('The trail bottle keeps drinks cold for 18 hours.', {\n      id: 'sku-trail-bottle',\n      category: 'drinkware',\n      inventoryStatus: 'in_stock',\n    }),\n  ],\n});\n```\n\n### Delete documents by id\n\nUse the same `ai.index()` call with delete options:\n\n```ts\nawait ai.index({\n  indexer: productsIndexer,\n  documents: [],\n  options: {\n    operation: 'delete',\n    ids: ['sku-trail-bottle'],\n  },\n});\n```\n\nYou can also omit `options.ids` and pass documents that contain `metadata.id`.\n\n### Retrieve documents\n\n```ts\nimport { supabaseRetrieverRef } from '@sudodevstudio/genkitx-supabase';\n\nconst productsRetriever = supabaseRetrieverRef('products');\n\nconst docs = await ai.retrieve({\n  retriever: productsRetriever,\n  query: 'Which bag fits a laptop?',\n  options: { k: 3 },\n});\n```\n\n### Metadata filter example\n\nMetadata filters are passed to the RPC function as JSONB and work well with `metadata @\u003e filter`.\n\n```ts\nconst docs = await ai.retrieve({\n  retriever: productsRetriever,\n  query: 'Show me in-stock bags',\n  options: {\n    k: 5,\n    filter: {\n      category: 'bags',\n      inventoryStatus: 'in_stock',\n    },\n  },\n});\n```\n\n## Public API\n\n### `supabaseVectorStore(configs)`\n\nRegisters one or more Supabase-backed vector stores by `indexName`.\n\nConfig fields:\n\n- `indexName`\n- `embedder`\n- `connection: { url, key }`\n- `table?`\n- `queryRpcName?`\n- `idColumn?`\n- `contentColumn?`\n- `metadataColumn?`\n- `embeddingColumn?`\n- `schema?`\n- `defaultK?`\n- `embeddingDimension?`\n- `embedderOptions?`\n\nDefaults:\n\n- `schema: 'public'`\n- `table: 'rag_documents'`\n- `queryRpcName: 'match_rag_documents'`\n- `idColumn: 'id'`\n- `contentColumn: 'content'`\n- `metadataColumn: 'metadata'`\n- `embeddingColumn: 'embedding'`\n- `defaultK: 3`\n\n### `supabaseIndexerRef(indexName)`\n\nReturns the Genkit indexer reference for `ai.index()`.\n\nSupported indexer options:\n\n- `operation?: 'upsert' | 'delete'`\n- `ids?: Array\u003cstring | number\u003e`\n- `batchSize?: number`\n\n### `supabaseRetrieverRef(indexName)`\n\nReturns the Genkit retriever reference for `ai.retrieve()`.\n\nSupported retriever options:\n\n- `k?: number`\n- `filter?: Record\u003cstring, unknown\u003e`\n\n## Production Notes\n\n- Use a service role key on trusted servers only. Do not expose it in browser bundles.\n- Keep retrieval and indexing on the server side, especially when your table or RPC requires elevated database permissions.\n- Make sure the RPC function lives in an exposed schema and that Row Level Security policies allow the operations you need.\n- Keep your `embeddingDimension` aligned with the actual vector column dimension to catch mistakes before they hit Postgres.\n\n## Repository Contents\n\n- source: [`src/index.ts`](./src/index.ts)\n- SQL: [`sql/001_create_rag_documents.sql`](./sql/001_create_rag_documents.sql), [`sql/002_match_rag_documents.sql`](./sql/002_match_rag_documents.sql)\n- tests: [`test/config.test.ts`](./test/config.test.ts), [`test/mapping.test.ts`](./test/mapping.test.ts), [`test/filter.test.ts`](./test/filter.test.ts), [`test/store.test.ts`](./test/store.test.ts)\n\n## License\nSee [`LICENSE`](./LICENSE) for the full terms.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsudodevstudio%2Fgenkitx-supabase","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsudodevstudio%2Fgenkitx-supabase","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsudodevstudio%2Fgenkitx-supabase/lists"}