{"id":21332536,"url":"https://github.com/notrab/libsql-vector","last_synced_at":"2025-10-05T12:53:10.685Z","repository":{"id":257813744,"uuid":"863819263","full_name":"notrab/libsql-vector","owner":"notrab","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-03T05:09:44.000Z","size":64,"stargazers_count":11,"open_issues_count":11,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-03T07:08:20.715Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/notrab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2024-09-27T01:15:40.000Z","updated_at":"2025-04-29T07:53:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"16ef48c1-b190-4573-b597-7320ecb23812","html_url":"https://github.com/notrab/libsql-vector","commit_stats":null,"previous_names":["notrab/libsql-vector"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/notrab/libsql-vector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notrab%2Flibsql-vector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notrab%2Flibsql-vector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notrab%2Flibsql-vector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notrab%2Flibsql-vector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/notrab","download_url":"https://codeload.github.com/notrab/libsql-vector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notrab%2Flibsql-vector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278457469,"owners_count":25989956,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"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":"2024-11-21T22:52:14.204Z","updated_at":"2025-10-05T12:53:10.667Z","avatar_url":"https://github.com/notrab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# libsql-vector\n\nVector similarity search for libSQL and Turso.\n\n```bash\nnpm install libsql-vector\n```\n\n## Usage\n\n### Initializing the Index\n\n```typescript\nimport { createClient } from \"@libsql/client\";\nimport { Index } from \"libsql-vector\";\n\nconst client = createClient({ url: \"file:vector.db\" });\nconst vectorIndex = new Index(client, {\n  tableName: \"my_vectors\", // optional, defaults to 'vector_index'\n  dimensions: 384,\n  columns: [\n    { name: \"title\", type: \"TEXT\" },\n    { name: \"timestamp\", type: \"INTEGER\" },\n  ],\n  debug: process.env.NODE_ENV !== \"production\", // optional, defaults to false\n});\n\n// Initialize the index (creates table and index if they don't exist)\nawait vectorIndex.initialize();\n```\n\n### Upserting Vectors\n\n```typescript\nconst vectors = [\n  {\n    id: \"1\",\n    vector: [0.1, 0.2, 0.3 /* ... up to 384 dimensions */],\n    title: \"Example Document 1\",\n    timestamp: Date.now(),\n  },\n  {\n    id: \"2\",\n    vector: [0.4, 0.5, 0.6 /* ... up to 384 dimensions */],\n    title: \"Example Document 2\",\n    timestamp: Date.now(),\n  },\n];\n\nawait vectorIndex.upsert(vectors);\n```\n\n### Querying Vectors\n\n```typescript\nconst queryVector = [0.2, 0.3, 0.4 /* ... up to 384 dimensions */];\n\n// Basic query\nconst results = await vectorIndex.query(queryVector, { topK: 5 });\n\nconsole.log(results);\n// [\n//   { id: '1', score: 0.95, title: 'Example Document 1', timestamp: 1631234567890 },\n//   { id: '2', score: 0.82, title: 'Example Document 2', timestamp: 1631234567891 },\n//   ...\n// ]\n\n// Query with filter\nconst filteredResults = await vectorIndex.query(queryVector, {\n  topK: 5,\n  filter: \"timestamp \u003e 1630000000000\",\n});\n\n// Query including vector data\nconst resultsWithVectors = await vectorIndex.query(queryVector, {\n  topK: 5,\n  includeVectors: true,\n});\n\nconsole.log(resultsWithVectors);\n// [\n//   {\n//     id: '1',\n//     score: 0.95,\n//     title: 'Example Document 1',\n//     timestamp: 1631234567890,\n//     vector: [0.1, 0.2, 0.3, ...]\n//   },\n//   ...\n// ]\n```\n\n### Listing Vectors\n\n```typescript\n// List vectors with default options\nconst result = await vectorIndex.list();\n\nconsole.log(result);\n// {\n//   items: [\n//     { id: '1', metadata: { title: 'Example Document 1', timestamp: 1631234567890 } },\n//     { id: '2', metadata: { title: 'Example Document 2', timestamp: 1631234567891 } },\n//     ...\n//   ],\n//   nextCursor: '10'\n// }\n\n// List vectors with custom options\nconst customResult = await vectorIndex.list({\n  cursor: \"10\",\n  limit: 5,\n  includeVectors: true,\n  includeMetadata: false,\n});\n\nconsole.log(customResult);\n// {\n//   items: [\n//     { id: '11', vector: [0.1, 0.2, 0.3, ...] },\n//     { id: '12', vector: [0.4, 0.5, 0.6, ...] },\n//     ...\n//   ],\n//   nextCursor: '15'\n// }\n```\n\n### Retrieving Vectors\n\n```typescript\n// Retrieve a single vector\nconst vector = await vectorIndex.retrieve(\"1\");\n\nconsole.log(vector);\n// {\n//   id: '1',\n//   vector: [0.1, 0.2, 0.3, ...],\n//   metadata: { title: 'Example Document 1', timestamp: 1631234567890 }\n// }\n\n// Retrieve multiple vectors\nconst vectors = await vectorIndex.retrieve([\"1\", \"2\"]);\n\nconsole.log(vectors);\n// [\n//   {\n//     id: '1',\n//     vector: [0.1, 0.2, 0.3, ...],\n//     metadata: { title: 'Example Document 1', timestamp: 1631234567890 }\n//   },\n//   {\n//     id: '2',\n//     vector: [0.4, 0.5, 0.6, ...],\n//     metadata: { title: 'Example Document 2', timestamp: 1631234567891 }\n//   }\n// ]\n\n// Retrieve without vector or metadata\nconst vectorWithoutDetails = await vectorIndex.retrieve(\"1\", {\n  includeVector: false,\n  includeMetadata: false,\n});\n\nconsole.log(vectorWithoutDetails);\n// { id: '1' }\n```\n\n## API Reference\n\n### `new Index(client, options)`\n\nCreates a new vector index.\n\n- `client`: A libSQL client instance\n- `options`: Configuration options\n  - `tableName`: Name of the table to store vectors (default: `vector_index`)\n  - `dimensions`: Number of dimensions in your vectors\n  - `columns`: Additional columns to store with each vector\n  - `debug`: Enable debug logging (default: `false`)\n\n### `index.initialize()`\n\nInitializes the index, creating the necessary table and index if they don't exist.\n\n### `index.upsert(vectors)`\n\nInserts or updates vectors in the index.\n\n- `vectors`: An array of vector objects, each containing:\n  - `id`: Unique identifier for the vector\n  - `vector`: Array of numbers representing the vector\n  - Additional properties corresponding to the columns defined in the index options\n\n### `index.query(queryVector, options)`\n\nPerforms a similarity search.\n\n- `queryVector`: Array of numbers representing the query vector\n- `options`:\n  - `topK`: Number of results to return\n  - `filter`: SQL WHERE clause to filter results (optional)\n  - `includeVectors`: Whether to include vector data in the results (default: `false`)\n\nReturns an array of results, each containing the vector's id, similarity score, and additional columns.\n\n### `index.list(options)`\n\nLists vectors in the index with pagination.\n\n- `options`:\n  - `cursor`: Pagination cursor (optional)\n  - `limit`: Number of items to return (default: 10)\n  - `includeVectors`: Whether to include vector data in the results (default: false)\n  - `includeMetadata`: Whether to include metadata in the results (default: true)\n\nReturns an object with `items` array and `nextCursor` for pagination.\n\n### `index.retrieve(ids, options)`\n\nRetrieves one or more vectors by their IDs.\n\n- `ids`: A single ID or an array of IDs\n- `options`:\n  - `includeVector`: Whether to include vector data in the results (default: true)\n  - `includeMetadata`: Whether to include metadata in the results (default: true)\n\nReturns a single vector object or an array of vector objects.\n\n## License\n\n[MIT](https://choosealicense.com/licenses/mit/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotrab%2Flibsql-vector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnotrab%2Flibsql-vector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotrab%2Flibsql-vector/lists"}