Searching for records

As you insert data into Xata, it is automatically indexed for full-text search. You can run a search by using the /search endpoint. Unlike the /query endpoint, which lives at the table level, the /search endpoint lives at the database branch level, allowing you to search across all tables in the database at once.

The search index is updated asynchronously after each insert/update, meaning that the search results are eventually consistent with the results that you get from the /query endpoint.

The format of a search request is as follows:

// POST https://{your-workspace-slug}.xata.sh/db/{db_branch_name}/search

{
  "tables": [...], // array of table names as strings
  "query": "the search query",
  "fuzziness": 1
}

A simple example, which searches across all tables with default relevancy settings, looks like this:

// POST https://tutorial-ng7s8c.xata.sh/db/tutorial:main/search

{
  "query": "new st"
}

Which returns results in the following format:

{
  "records": [
    {
      "address": {
        "street": "123 New St",
        "zipcode": 12345
      },
      "email": "keanu@example.com",
      "full_name": "Keanu Reeves",
      "id": "rec_c8stghniqa4ckd0ao9q0",
      "xata": {
        "version": 3,
        "table": "users"
      }
    }
  ]
}

Because the search works across tables, the xata.table field is included in the returned records to indicate which table the record came from.

Restricting Search By Tables

If you'd like to search only some of the tables in the database, you can specify the tables to search in the tables field of the request. It expects an array, for example:

// POST https://tutorial-ng7s8c.xata.sh/db/tutorial:main/search

{
  "query": "new st",
  "tables": ["users", "teams"]
}

Fuzziness and Typo Tolerance

By default, Xata searches tolerate typos of one character. You can control this behavior by setting the fuzziness parameter, which represents the maximum Levenshtein distance for the search terms. Informally, the Levenshtein distance between two words is the minimum number of single-character edits (insertions, deletions or substitutions) required to change one word into the other. Xata accepts 3 possible values:

  • 0: no typo tolerance
  • 1: one letter changed/added/removed (default)
  • 2: two letters changed/added/removed

For example, instead of Keanu you can search for kaanu (one letter replaced) or kenu (one letter missing) and still get the same result:

// POST https://tutorial-ng7s8c.xata.sh/db/tutorial:main/search

{
  "query": "kaanu"
}

The above matches Keanu. You can disable this typo tolerance by setting the fuzziness field to 0:

// POST https://tutorial-ng7s8c.xata.sh/db/tutorial:main/search

{
  "query": "kaanu",
  "fuzziness": 0
}

The above won't match Keanu.

You can also increase the fuzzyness to accept two typos per word:

// POST https://tutorial-ng7s8c.xata.sh/db/tutorial:main/search

{
  "query": "kaano",
  "fuzziness": 2
}

The above will match records containing Keanu.

Next Steps

If you're here, there's a great chance you've completed our guide on working with records. If so, we'd recommend exploring the API reference to get more familiar with our API. If not, feel free to visit the pages on getting data from a database. Alternatively, we can also look into updating data, inserting data, or deleting data. We've got guides for each of these operations.


Last modified 1 mo1 day ago