---
title: Querying
description: One call searches an index by text, by vector or by both, and answers the best match first.
type: how-to
product: search
summary: The query call, the three fields it takes, and what a hit carries.
updated: 2026-09-28
order: 1
---

A query is one call to one index, and the index decides the ranking: the hits
come back best match first.

```bash
curl -X POST "https://api.data.sylphx.com/v1/search/index-id" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

`index-id` is the id segment of the index's name in the environment. The call
needs `data:read`, and it is served on the data host beside the documents it
reads.

## Three fields

<PropertyTable
	properties={[
		{
			name: 'query',
			type: 'string',
			description: 'Text to match.',
		},
		{
			name: 'vector',
			type: 'double[]',
			description: 'An embedding to match by nearness.',
		},
		{
			name: 'limit',
			type: 'uint32',
			description: 'At most this many hits, 1 to 100; unset is 20.',
		},
	]}
/>

`query` is the lexical half: text, matched against the words in the documents.
`vector` is the other half of the same index: an embedding you supply, matched
by nearness to the embeddings written with the documents. Send one or send
both. A text query works in every index; a vector query needs an index with a
positive `vector_dimensions`, because there is nothing else to compare an
embedding against — and Data never invents one.

`limit` is a cap rather than a page: the answer is the best `limit` hits, and
there is no token to continue from.

## What comes back

The answer is `hits`, best first. A hit is the document the index stored, plus
the number it matched by:

<PropertyTable
	properties={[
		{
			name: 'document',
			type: 'DocumentRecord',
			description: 'The document.',
		},
		{
			name: 'score',
			type: 'double',
			description: 'How well it matched; higher is better.',
		},
	]}
/>

A hit carries the whole record — `document_json`, `vector`, `version`,
`sha256` — so a result is enough to act on without a second read, and the
order of `hits` is the order of `score`.

<RelatedDocs
	links={[
		{
			href: '/docs/search/indexing',
			label: 'Indexing documents',
			description: 'The documents a query reads, and the vectors they carry.',
		},
		{
			href: '/docs/api/search',
			label: 'The search collection',
			description: 'The query method, its scope and its examples.',
		},
		{
			href: '/docs/search/quickstart',
			label: 'Quickstart',
			description: 'Create an index, write a document and query it.',
		},
	]}
/>