• MATCHES
  • SCHEMA
  • HUMAN
  • CONTEXT

How to run vector similarity searches with your AI

Connect your AI to ClickHouse once. From then on, your agent can query high-dimensional embeddings to find the most relevant data points.

Ask AI about this page

Short answer

How can I perform vector similarity searches using my AI?

You pass high-dimensional embeddings to ClickHouse, where the engine calculates distance metrics to find the closest matches. Your agent handles the query logic and interprets the results. You get a list of the most relevant records based on semantic similarity.

Search outcomes

Where your results land

What happens when you run a similarity query.

MATCHES

Relevant record sets

The AI identifies the closest vectors in your ClickHouse tables. You receive the specific rows that meet your similarity threshold.

SCHEMA

Table structure insights

The agent inspects your vector columns to understand the dimensions and types. This ensures the search parameters match your actual data.

HUMAN

Manual validation

You review the returned matches to ensure the semantic distance actually represents the relationship you're looking for.

CONTEXT

Semantic retrieval

The AI uses the retrieved vectors to answer questions or provide context for larger tasks. This turns raw numbers into usable information.

The workflow

What your AI does when the query arrives.

The AI acts as the bridge between your natural language intent and the mathematical operations in ClickHouse.

  1. Inspect data structure

    The agent looks at your ClickHouse tables to find the specific columns holding your embeddings.

    describe_table

  2. Execute similarity search

    Your AI sends the embedding vector to ClickHouse to run the distance calculation against your stored data.

    vector_search

  3. Filter results

    The agent uses the returned distance scores to narrow down the most accurate matches for your request.

    vector_search

  4. Present findings

    The AI translates the raw database rows into a readable format that answers your specific question.

    describe_table

Try it

Copy these to start.

Use these prompts to trigger searches immediately.

Starting points

Replace the table and column names with your actual ClickHouse identifiers.

ClickHouse Connector

You're all set. Choose your MCP client and follow the setup instructions.

Connector linkhttps://edge.vinkius.com/vk_preview_567ij3B5hJvT6KRM8Z5LcFbGNttrwDvwD2OPp6c2/mcp

Claude Desktop

Follow the steps below to connect in seconds.

  1. 1In Claude Desktop, open Settings → Connectors.
  2. 2Click “Add custom connector” and paste the connector link above as the remote MCP server URL.
  3. 3Click Add and start a new chat — ClickHouse capabilities are ready to use.
Configuration · claude_desktop_config.jsonCopy
{
  "mcpServers": {
    "clickhouse-vector-search-mcp": {
      "url": "https://edge.vinkius.com/vk_preview_567ij3B5hJvT6KRM8Z5LcFbGNttrwDvwD2OPp6c2/mcp"
    }
  }
}
Copy into chat04

  • Find the top 5 most similar records in the 'products' table using the embedding column.

  • Describe the 'user_embeddings' table so I know which columns to use for a search.

  • Search for records in the 'documents' table that are semantically close to this vector: [0.1, 0.2, 0.3].

  • Show me the schema for the 'embeddings_store' table to prepare for a similarity query.

  • Claude
  • ChatGPT
  • Cursor
  • VS Code
  • Windsurf
  • Claude Code
  • JetBrains
  • Cline

Start here

Connect ClickHouse once, then ask.

Enter your credentials once to establish the connection. Your AI client will then have direct access to your ClickHouse vector data.

Connect ClickHouse to your AI

FAQ

How this task behaves

  • 01

    Can the AI change my ClickHouse table schema?

    No. The AI can only read the table structure to understand how to perform searches.

  • 02

    Will the AI delete any of my vector data?

    No. This MCP only provides tools for describing tables and performing searches.

  • 03

    Do I need to provide the embedding vector myself?

    Yes, for a similarity search, you must provide the vector you want to use as the query point.

  • 04

    Can the AI run standard SQL queries?

    No. The AI is limited to the specific vector search and table description tools provided.

  • 05

    How does the AI know which table to search?

    You specify the table name in your prompt, or the AI uses the describe tool to find the right one.

  • More questions about ClickHouse? The Connector page answers them. See everything the ClickHouse Connector can do

Connect ClickHouse to Claude, Cursor, ChatGPT & more