Search quickstart

This takes an environment to a queried index. The index itself is a CLI or API call on the one API; its documents and queries are calls to the data host.

#1. Create the index

The parent is the environment it belongs to. An empty spec is a valid request, and it makes a lexical index.

sylphx data search-indexes create --parent orgs/acme/projects/shop/envs/production

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/search_indexes" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spec":{}}'

create answers with an Operation, and the Operation settles with the index. The final name segment is yours to choose, or the server's to assign when you leave it out; the run lines on this page address the index as search-index. A positive --spec.vector-dimensions is what adds cosine queries, and the embeddings you write must then be that long.

#2. Take the connection

An index's engine credentials are not kept anywhere for you to copy. Ask for them, and they are returned to that caller only:

sylphx data search-indexes connect orgs/acme/projects/shop/envs/production/search_indexes/search-index

The answer carries the host ({ref}.sylphx.net), the TLS port (8108 for a search index), the engine user and password, and a uri that embeds them. connect asks for data:write: nothing is written, but the answer is a credential.

#3. Write a document

The path carries both ids: index-id is the id segment of the index's name, and document-id is the document's own id. The pair is the document's address.

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

A PUT replaces the current version of that address — there is no partial update. The body carries the document as JSON (document_json, base64, at most 1 MiB) and, in an index with dimensions, the vector you supply. expected_version makes the write conditional on the version you last read.

The answer is the stored record: the document back, with its version, sha256 and updated_at_unix_ms.

#4. Query it

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

The body takes query (text), vector (an embedding), or both, and limit caps the answer — 1 to 100 hits, 20 when unset. The answer is hits, best match first, each one the stored document plus the score it matched with.

#5. Delete the document

curl -X DELETE "https://api.data.sylphx.com/v1/documents/index-id/document-id" \
  -H "Authorization: Bearer $SYLPHX_API_KEY"

The answer says whether the document existed, so a delete that finds nothing is still a successful call. expected_version in the query makes the delete as conditional as the write.

#6. Delete the index

sylphx data search-indexes delete orgs/acme/projects/shop/envs/production/search_indexes/search-index --yes