Performs vector similarity search

Instructions

Implementation Reference

• src/tools/handler.ts:53-59 (schema)

  VectorSearchSchema - Zod schema defining the input parameters for vector_search tool: table, vector_column, query_vector (number array), limit (optional), and database (optional).

  const VectorSearchSchema = z.object({
  	table: z.string().describe('Table name'),
  	vector_column: z.string().describe('Column containing vectors'),
  	query_vector: z.array(z.number()).describe('Query vector for similarity search'),
  	limit: z.number().optional().describe('Maximum number of results (optional, default 10)'),
  	database: z.string().optional().describe('Database name (optional, uses context if not provided)'),
  });

• src/tools/handler.ts:316-359 (handler)

  The vector_search tool handler - constructs a SQL query using vector_distance() and vector_from_json() functions, executes it via the database client, and returns formatted results with distances.

  server.tool(
  	{
  		name: 'vector_search',
  		description: 'Performs vector similarity search',
  		schema: VectorSearchSchema,
  	},
  	async ({ table, vector_column, query_vector, limit = 10, database }) => {
  		try {
  			const database_name = resolve_database_name(database);
  			if (database) set_current_database(database);
  
  			// Construct a vector search query using SQLite's vector functions
  			const vector_string = query_vector.join(',');
  			const query = `
           SELECT *, vector_distance(${vector_column}, vector_from_json(?)) as distance
           FROM ${table}
           ORDER BY distance ASC
           LIMIT ?
         `;
  
  			const params = {
  				1: `[${vector_string}]`,
  				2: limit,
  			};
  
  			const result = await database_client.execute_query(
  				database_name,
  				query,
  				params,
  			);
  
  			const formatted_result = format_query_result(result);
  			return create_tool_response({
  				database: database_name,
  				table,
  				vector_column,
  				query_vector,
  				results: formatted_result,
  			});
  		} catch (error) {
  			return create_tool_error_response(error);
  		}
  	},
  );

• src/tools/handler.ts:316-359 (registration)

  Tool registration via server.tool() call with name 'vector_search', description 'Performs vector similarity search', and the VectorSearchSchema.

  server.tool(
  	{
  		name: 'vector_search',
  		description: 'Performs vector similarity search',
  		schema: VectorSearchSchema,
  	},
  	async ({ table, vector_column, query_vector, limit = 10, database }) => {
  		try {
  			const database_name = resolve_database_name(database);
  			if (database) set_current_database(database);
  
  			// Construct a vector search query using SQLite's vector functions
  			const vector_string = query_vector.join(',');
  			const query = `
           SELECT *, vector_distance(${vector_column}, vector_from_json(?)) as distance
           FROM ${table}
           ORDER BY distance ASC
           LIMIT ?
         `;
  
  			const params = {
  				1: `[${vector_string}]`,
  				2: limit,
  			};
  
  			const result = await database_client.execute_query(
  				database_name,
  				query,
  				params,
  			);
  
  			const formatted_result = format_query_result(result);
  			return create_tool_response({
  				database: database_name,
  				table,
  				vector_column,
  				query_vector,
  				results: formatted_result,
  			});
  		} catch (error) {
  			return create_tool_error_response(error);
  		}
  	},
  );

• src/clients/database.ts:120-151 (helper)

  The execute_query helper function used by the vector_search handler to execute the generated SQL query against a Turso database via the libSQL client.

  export async function execute_query(
  	database_name: string,
  	query: string,
  	params: Record<string, any> = {},
  ): Promise<ResultSet> {
  	try {
  		// Determine if this is a read-only query
  		const is_read_only = query
  			.trim()
  			.toLowerCase()
  			.startsWith('select');
  		const permission = is_read_only ? 'read-only' : 'full-access';
  
  		const client = await get_database_client(
  			database_name,
  			permission,
  		);
  
  		// Execute the query
  		return await client.execute({
  			sql: query,
  			args: convert_parameters(params),
  		});
  	} catch (error) {
  		throw new TursoApiError(
  			`Failed to execute query for database ${database_name}: ${
  				(error as Error).message
  			}`,
  			500,
  		);
  	}
  }

• src/tools/context.ts:37-49 (helper)

  The resolve_database_name helper used by the vector_search handler to determine which database to query, falling back to context or config default.

  export function resolve_database_name(
  	provided_name?: string,
  ): string {
  	const database_name = provided_name || get_current_database();
  
  	if (!database_name) {
  		throw new Error(
  			'No database specified. Please provide a database name or set a default database.',
  		);
  	}
  
  	return database_name;
  }