{"id":22533,"library":"vecs","title":"vecs","description":"vecs is a pgvector client library by Supabase for managing and querying vector collections backed by PostgreSQL with pgvector. Current version 0.4.5. Release cadence is irregular; latest updates in 2024.","status":"active","version":"0.4.5","language":"python","source_language":"en","source_url":"https://github.com/supabase/vecs","tags":["postgres","pgvector","vector-database","embeddings","supabase"],"install":[{"cmd":"pip install vecs","lang":"bash","label":"Install vecs"}],"dependencies":[],"imports":[{"note":"The main object is 'vecs.Client', not 'vecs.client' or 'vecs.Vecs'.","wrong":"","symbol":"Client","correct":"import vecs"},{"note":"Collection is a class used for managing vector collections.","wrong":"","symbol":"Collection","correct":"from vecs import Collection"}],"quickstart":{"code":"import vecs\n\nDB_CONNECTION = \"postgresql://user:pass@host:5432/db\"\nvx = vecs.Client(DB_CONNECTION)\n\n# Create a collection of vectors with 384 dimensions\ndocs = vx.create_collection(name=\"docs\", dimension=384)\n\n# Add vectors\ndocs.upsert(\n    records=[\n        (\"vec0\", [0.1, 0.2, ...], {\"key\": \"val\"}),  # truncated for brevity\n        (\"vec1\", [0.3, 0.4, ...], {}),\n    ]\n)\ndocs.create_index()\n\n# Query\nresults = docs.query(\n    data=[0.1, 0.2, ...],\n    limit=5,\n    filters={\"key\": {\"$eq\": \"val\"}}\n)\nprint(results)","lang":"python","description":"Connect to a Supabase Postgres instance with pgvector, create a collection, upsert vectors, and query."},"warnings":[{"fix":"Use 'import vecs; vx = vecs.Client(DB_CONNECTION)'.","message":"The library changed from using 'vecs.Client' to 'vecs.Client' (no change) but the underlying API for creating collections changed from 'create_collection' to the current pattern. Old code using 'vecs.client' (lowercase) or 'vecs.create_client' will fail.","severity":"breaking","affected_versions":"<=0.3.x vs 0.4.x"},{"fix":"Convert numpy arrays to list: vector.tolist().","message":"The 'upsert' method expects records as a list of tuples: (id, vector, metadata). The vector must be a list of floats. Passing numpy arrays may cause issues.","severity":"gotcha","affected_versions":"all"},{"fix":"Use 'docs.create_index(measure=vecs.IndexMeasure.cosine_distance, index=vecs.IndexMethod.ivfflat, params=dict(lists=100))'.","message":"Creating an index with 'create_index()' is not automatic; you must call it after upserting data for good performance. Default index is IVFFlat with no parameters; consider specifying index type and parameters.","severity":"gotcha","affected_versions":"all"},{"fix":"Replace 'upsert_docs' with 'upsert' and 'query_docs' with 'query'.","message":"The method 'upsert_docs' and 'query_docs' have been removed. Use 'upsert' and 'query'.","severity":"deprecated","affected_versions":">=0.4.0"},{"fix":"Check the distance metric used when interpreting results.","message":"The 'query' method returns a list of tuples (id, distance, metadata). The distance is the actual distance, not similarity. For cosine distance, lower is better.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run 'pip install vecs' and ensure you are using the correct Python environment.","cause":"vecs is not installed or installed in a different environment.","error":"ModuleNotFoundError: No module named 'vecs'"},{"fix":"Use 'vx = vecs.Client(DB_CONNECTION)' without additional arguments.","cause":"Old code using 'vecs.Client(DB_CONNECTION)' used to allow an extra argument or the import pattern changed.","error":"TypeError: Client() takes 1 positional argument but 2 were given"},{"fix":"Use 'vecs.Client' with capital C.","cause":"Trying to access lowercase 'vecs.client' instead of 'vecs.Client'.","error":"AttributeError: module 'vecs' has no attribute 'client'"},{"fix":"Run 'CREATE EXTENSION vector;' in the PostgreSQL database.","cause":"The PostgreSQL extension 'vector' (pgvector) is not installed in the database.","error":"psycopg2.errors.UndefinedObject: type \"vector\" does not exist"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}