{"slug": "semantic-search-with-postgresql-pragmatism-beats-hype-most-of-the-time", "title": "Semantic Search with PostgreSQL: Pragmatism Beats Hype - Most of the Time", "summary": "A developer advocates using PostgreSQL with the pgvector extension for semantic search instead of dedicated vector databases like Pinecone or Weaviate. The approach reduces infrastructure complexity by storing embeddings alongside relational data and querying with SQL. Key considerations include choosing a consistent embedding model and chunking documents for better search accuracy.", "body_md": "When you start adding semantic search to an application, the obvious options are often Pinecone, Weaviate, Qdrant, Milvus, or another dedicated vector database.\n\nThat can be the right choice.\n\nBut many applications already have a PostgreSQL database running. And for a large class of semantic search use cases, that database can do the job directly.\n\nThe key is `pgvector`\n\n, an open-source PostgreSQL extension that adds vector types and vector similarity search to Postgres. It lets you store embeddings next to your relational data and query them with SQL.\n\nThe advantage is not only fewer moving parts. It is also architectural:\n\nNo separate sync pipeline, no second source of truth, and no extra infrastructure until you actually need it.\n\nClassic search compares words. Semantic search compares meaning.\n\nThe query \"How do I get over the pass?\" can find a text about a mountain pass rather than a school hallway because both the query and the documents are represented as numerical vectors, also called embeddings.\n\nThe basic flow is:\n\nThe phrase \"same vector space\" matters. You cannot freely mix embeddings from different models.\n\nBefore creating the database schema, choose the embedding model.\n\nThat choice determines:\n\nFor example, if you use OpenAI `text-embedding-3-small`\n\n, a `vector(1536)`\n\ncolumn is a common fit. If you use another model, including a local model through Ollama, the dimension may be different.\n\nThis is not a detail. PostgreSQL will reject vectors with the wrong number of dimensions.\n\nIf you later change the embedding model, plan to:\n\nEmbedding model changes are data migrations.\n\nEnable the extension once in the database:\n\n```\nCREATE EXTENSION IF NOT EXISTS vector;\n```\n\nWith managed PostgreSQL providers, check whether `pgvector`\n\nis available on your plan and PostgreSQL version. Many providers support it, but you should verify this before designing around it.\n\nFor small records, one vector per row is fine.\n\nFor real documents, it is usually better to embed chunks. A long document may cover several topics. One vector for the entire document often becomes too blurry.\n\nA practical schema:\n\n```\nCREATE TABLE documents (\n    id          BIGSERIAL PRIMARY KEY,\n    title       TEXT NOT NULL,\n    source      TEXT,\n    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()\n);\n\nCREATE TABLE document_chunks (\n    id           BIGSERIAL PRIMARY KEY,\n    document_id  BIGINT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,\n    chunk_index  INTEGER NOT NULL,\n    content      TEXT NOT NULL,\n    embedding    vector(1536) NOT NULL,\n    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n    UNIQUE (document_id, chunk_index)\n);\n```\n\nUse `vector(1536)`\n\nonly if your embedding model actually returns 1536-dimensional vectors. Otherwise, change the dimension to match the model.\n\nInstall the packages:\n\n```\ndotnet add package Npgsql\ndotnet add package Pgvector\n```\n\nIf you use Dapper, also add:\n\n```\ndotnet add package Pgvector.Dapper\n```\n\nFor raw Npgsql, configure the data source with `UseVector()`\n\n:\n\n``` js\nusing Npgsql;\nusing Pgvector;\n\nvar dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);\ndataSourceBuilder.UseVector();\n\nawait using var dataSource = dataSourceBuilder.Build();\n```\n\nIn production, create the extension and tables through migrations or database provisioning. If you create the extension at runtime, reload PostgreSQL types on the connection before using the new type.\n\nWith the OpenAI .NET SDK:\n\n``` js\nusing OpenAI.Embeddings;\n\nvar embeddingClient = new EmbeddingClient(\"text-embedding-3-small\", apiKey);\n\nasync Task<float[]> GetEmbeddingAsync(string text)\n{\n    var result = await embeddingClient.GenerateEmbeddingAsync(text);\n    return result.Value.ToFloats().ToArray();\n}\n```\n\nFor local embeddings, use a local embedding model through your preferred provider. The important rule is the same:\n\nThe model used for indexing and the model used for querying must be the same, or at least intentionally compatible.\n\nDo not index documents with one model and query them with another.\n\n```\nasync Task InsertChunkAsync(\n    long documentId,\n    int chunkIndex,\n    string content,\n    CancellationToken cancellationToken = default)\n{\n    var embedding = await GetEmbeddingAsync(content);\n    var vector = new Vector(embedding);\n\n    await using var conn = await dataSource.OpenConnectionAsync(cancellationToken);\n    await using var cmd = new NpgsqlCommand(\"\"\"\n        INSERT INTO document_chunks (document_id, chunk_index, content, embedding)\n        VALUES (@documentId, @chunkIndex, @content, @embedding)\n        ON CONFLICT (document_id, chunk_index)\n        DO UPDATE SET\n            content = EXCLUDED.content,\n            embedding = EXCLUDED.embedding\n        \"\"\", conn);\n\n    cmd.Parameters.AddWithValue(\"documentId\", documentId);\n    cmd.Parameters.AddWithValue(\"chunkIndex\", chunkIndex);\n    cmd.Parameters.AddWithValue(\"content\", content);\n    cmd.Parameters.AddWithValue(\"embedding\", vector);\n\n    await cmd.ExecuteNonQueryAsync(cancellationToken);\n}\n```\n\nThe important part is the update path. If the content changes, the embedding must change too.\n\nThe `<=>`\n\noperator calculates cosine distance. A smaller value means higher similarity. `ORDER BY ... ASC`\n\nreturns the nearest vectors first.\n\n```\npublic sealed record SearchResult(\n    long DocumentId,\n    long ChunkId,\n    string Title,\n    string Content,\n    double Distance);\n\nasync Task<List<SearchResult>> SearchAsync(\n    string query,\n    int limit = 5,\n    CancellationToken cancellationToken = default)\n{\n    var queryEmbedding = await GetEmbeddingAsync(query);\n    var queryVector = new Vector(queryEmbedding);\n\n    await using var conn = await dataSource.OpenConnectionAsync(cancellationToken);\n    await using var cmd = new NpgsqlCommand(\"\"\"\n        SELECT d.id,\n               c.id,\n               d.title,\n               c.content,\n               c.embedding <=> @queryVector AS distance\n        FROM document_chunks c\n        JOIN documents d ON d.id = c.document_id\n        ORDER BY c.embedding <=> @queryVector\n        LIMIT @limit\n        \"\"\", conn);\n\n    cmd.Parameters.AddWithValue(\"queryVector\", queryVector);\n    cmd.Parameters.AddWithValue(\"limit\", limit);\n\n    var results = new List<SearchResult>();\n\n    await using var reader = await cmd.ExecuteReaderAsync(cancellationToken);\n    while (await reader.ReadAsync(cancellationToken))\n    {\n        results.Add(new SearchResult(\n            DocumentId: reader.GetInt64(0),\n            ChunkId: reader.GetInt64(1),\n            Title: reader.GetString(2),\n            Content: reader.GetString(3),\n            Distance: reader.GetDouble(4)));\n    }\n\n    return results;\n}\n```\n\nNotice that the query orders by the distance expression directly. With pgvector indexes, the `ORDER BY embedding <=> @query LIMIT n`\n\nshape is important.\n\npgvector supports several distance operators:\n\n| Operator | Meaning | Typical use |\n|---|---|---|\n`<=>` |\ncosine distance | text embeddings and semantic search |\n`<->` |\nL2 / Euclidean distance | general vector distance, images, spatial-like embeddings |\n`<#>` |\nnegative inner product | inner-product search; multiply by `-1` for the actual value |\n`<+>` |\nL1 distance | absolute-distance use cases |\n`<~>` |\nHamming distance | binary vectors |\n`<%>` |\nJaccard distance | binary vectors |\n\nFor most text embedding use cases, cosine distance is a good default.\n\nWithout an index, PostgreSQL scans the table for every vector search. That is exact and simple, but it becomes slow as the number of vectors grows.\n\nHNSW is often the best starting index for application search:\n\n```\nCREATE INDEX document_chunks_embedding_hnsw_idx\nON document_chunks\nUSING hnsw (embedding vector_cosine_ops)\nWITH (m = 16, ef_construction = 64);\n```\n\nThe parameters:\n\n`m`\n\n: maximum number of connections per layer; default is 16`ef_construction`\n\n: candidate list size during index construction; default is 64Higher values can improve recall, but increase memory usage and build time.\n\nYou can tune search recall per query:\n\n```\nSET hnsw.ef_search = 100;\n```\n\nor for one transaction:\n\n```\nBEGIN;\nSET LOCAL hnsw.ef_search = 100;\nSELECT ...\nCOMMIT;\n```\n\nImportant: HNSW is approximate. It trades perfect recall for speed.\n\nIVFFlat can use less memory and build faster than HNSW, but usually has a weaker speed-recall trade-off.\n\n```\nCREATE INDEX document_chunks_embedding_ivfflat_idx\nON document_chunks\nUSING ivfflat (embedding vector_cosine_ops)\nWITH (lists = 100);\n```\n\nDo not create an IVFFlat index on an empty table. It needs data to form the lists.\n\nA practical starting point for `lists`\n\n:\n\n`rows / 1000`\n\nfor up to 1M rows`sqrt(rows)`\n\nfor over 1M rowsFor 10,000 vectors, start around 10 lists, not 100.\n\nAt query time, tune probes:\n\n```\nSET ivfflat.probes = 10;\n```\n\nHigher probes improve recall and reduce speed.\n\nOne of the strongest reasons to use pgvector is that vectors live next to relational data.\n\nYou can filter before searching:\n\n``` js\nSELECT d.id, d.title, c.content, c.embedding <=> @queryVector AS distance\nFROM document_chunks c\nJOIN documents d ON d.id = c.document_id\nWHERE d.created_at > NOW() - INTERVAL '30 days'\n  AND d.source = 'documentation'\nORDER BY c.embedding <=> @queryVector\nLIMIT 10;\n```\n\nFor true hybrid search, do not just calculate keyword rank and then ignore it. Combine semantic and keyword ranks.\n\nOne practical pattern is Reciprocal Rank Fusion-style scoring:\n\n```\nWITH semantic AS (\n    SELECT c.id,\n           row_number() OVER (ORDER BY c.embedding <=> @queryVector) AS semantic_rank\n    FROM document_chunks c\n    LIMIT 100\n),\nkeyword AS (\n    SELECT c.id,\n           row_number() OVER (\n               ORDER BY ts_rank_cd(\n                   to_tsvector('english', c.content),\n                   plainto_tsquery('english', @query)\n               ) DESC\n           ) AS keyword_rank\n    FROM document_chunks c\n    WHERE to_tsvector('english', c.content) @@ plainto_tsquery('english', @query)\n    LIMIT 100\n)\nSELECT d.id AS document_id,\n       c.id AS chunk_id,\n       d.title,\n       c.content,\n       COALESCE(1.0 / (60 + semantic.semantic_rank), 0) +\n       COALESCE(1.0 / (60 + keyword.keyword_rank), 0) AS score\nFROM semantic\nFULL OUTER JOIN keyword ON keyword.id = semantic.id\nJOIN document_chunks c ON c.id = COALESCE(semantic.id, keyword.id)\nJOIN documents d ON d.id = c.document_id\nORDER BY score DESC\nLIMIT 10;\n```\n\nThis is not the only way to do hybrid search, but it makes the ranking logic explicit.\n\npgvector is a strong choice when:\n\nIt is especially good for internal search, product search, support tools, documentation search, and RAG systems where the relational database is already the source of truth.\n\nA dedicated vector database is worth considering when:\n\nThe decision is not ideology. It is operational fit.\n\n```\napp.MapGet(\"/search\", async (\n    string q,\n    NpgsqlDataSource db,\n    CancellationToken cancellationToken) =>\n{\n    var queryEmbedding = await GetEmbeddingAsync(q);\n    var queryVector = new Vector(queryEmbedding);\n\n    await using var conn = await db.OpenConnectionAsync(cancellationToken);\n    await using var cmd = new NpgsqlCommand(\"\"\"\n        SELECT d.id,\n               c.id,\n               d.title,\n               c.content,\n               c.embedding <=> @v AS distance\n        FROM document_chunks c\n        JOIN documents d ON d.id = c.document_id\n        ORDER BY c.embedding <=> @v\n        LIMIT 5\n        \"\"\", conn);\n\n    cmd.Parameters.AddWithValue(\"v\", queryVector);\n\n    var results = new List<object>();\n\n    await using var reader = await cmd.ExecuteReaderAsync(cancellationToken);\n    while (await reader.ReadAsync(cancellationToken))\n    {\n        results.Add(new\n        {\n            documentId = reader.GetInt64(0),\n            chunkId = reader.GetInt64(1),\n            title = reader.GetString(2),\n            content = reader.GetString(3),\n            distance = reader.GetDouble(4)\n        });\n    }\n\n    return Results.Ok(results);\n});\n```\n\nSemantic search does not always require a separate vector database.\n\nIf PostgreSQL is already your source of truth, pgvector lets you store embeddings next to relational data, query them with SQL, filter with normal PostgreSQL conditions, and keep transactions in one system.\n\nBut the clean version has a few rules:\n\nFor many production applications, pgvector is enough for a long time. Not because dedicated vector databases are unnecessary, but because the simplest reliable architecture is often the one that keeps the data where it already lives.", "url": "https://wpnews.pro/news/semantic-search-with-postgresql-pragmatism-beats-hype-most-of-the-time", "canonical_source": "https://dev.to/ben-witt/semantic-search-with-postgresql-pragmatism-beats-hype-most-of-the-time-25cg", "published_at": "2026-06-24 08:00:00+00:00", "updated_at": "2026-06-24 08:13:29.002539+00:00", "lang": "en", "topics": ["large-language-models", "developer-tools", "ai-infrastructure", "natural-language-processing", "ai-products"], "entities": ["PostgreSQL", "pgvector", "OpenAI", "text-embedding-3-small", "Pinecone", "Weaviate", "Qdrant", "Milvus"], "alternates": {"html": "https://wpnews.pro/news/semantic-search-with-postgresql-pragmatism-beats-hype-most-of-the-time", "markdown": "https://wpnews.pro/news/semantic-search-with-postgresql-pragmatism-beats-hype-most-of-the-time.md", "text": "https://wpnews.pro/news/semantic-search-with-postgresql-pragmatism-beats-hype-most-of-the-time.txt", "jsonld": "https://wpnews.pro/news/semantic-search-with-postgresql-pragmatism-beats-hype-most-of-the-time.jsonld"}}