Search

Overview

This endpoint allows you to search for documents within an index.

Endpoint

POST https://api.lixiasearch.com/v1/indexes/{indexId}/search

Usages

Basic usage

Define your query by setting the values to filter and their respective fields using the filters parameter. Specify the fields to be included in the results with the selectFields parameter. For each field, you have the option to retrieve its value and/or a snippet of the best match within the document based on the provided query.

{
    "filters": [
        {
            "type": "string",
            "name": "string",
            "values": ["string"]
        }
    ],
    "selectFields": [
        {
            "name": "string",
            "value": boolean,
            "snippet": {
                "escapeHtml": boolean,
                "length": int
            }
        }
    ],
    "offset": int
}

• filters: An array of filters
  • type: "field", the only supported filter
  • name: name of the field
  • values: values to filter on. The elements in the array are interpreted as an OR (any)

• selectFields: An array detailing the fields to return in the search results.

  • name: The name of the field.
  • value: A boolean indicating whether to include the field value in the search results.
  • snippet (optional): A parameter allowing retrieval of a snippet containing the best match within the document for the given query.
    • escapeHtml: A boolean indicating whether HTML escaping should be applied to the snippet.
    • length: An integer specifying the maximum length of the snippet.

• offset: The number of documents to skip before returning results.

Example

curl https://api.lixiasearch.com/v1/indexes/$INDEX_ID/search \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data @- << EOF
{
    "filters": [
        { "type": "field", "name": "body", "values": ["hello"] },
        { "type": "field", "name": "title", "values": ["hello"] }
    ],
    "offset": 0,
    "selectFields": [
        {
            "name": "id",
            "value": true
        },
         {
            "name": "title",
            "value": true
        },
        {
            "name": "body",
            "snippet": { "escapeHtml": true, "length": 200 },
            "value": false
        }
    ]
}
EOF

Make sure you replace $ACCESS_TOKEN with your actual access token and $INDEX_ID with the appropriate index id.

Response:

{
    "hasMoreDocuments": false,
    "hits": [
        {
            "fields": [
                {
                    "name": "body",
                    "snippet": "This is a <em>hello</em> world."
                },
                {
                    "name": "title",
                    "value": "Hello world"
                }
            ]
        },
        {
            "fields": [
                {
                    "name": "body",
                    "snippet": "A friendly <em>hello</em> from the data!"
                },
                {
                    "name": "title",
                    "value": "Data Greeting"
                }
            ]
        }
    ]
}

Custom Scoring

By default, Lixia Search assigns a score to each document based on its relevance to the query. You can customize this behavior if you created an index with fields declared as features. These fields can hold non-negative numeric values that indicate how good a document is, independently of the query (e.g., page rank score, reputation, or any other numeric value).

{
    ...
    "scoring": [{
        "type": "string",
        "weight": int,
        // other fields if necessary
    }]
}

• scoring: An array of scoring factors
  • type: words or feature
  • weight: the weight given to this scoring factor
  • name (only when type = feature): the name of the field containing the feature value

Example

In this example, we assign a weight of 6 to the document based on the specified query (words scoring factor). We also assign specific weights to two feature fields: 3 for reputation and 1 for inbound_links.

Therefore, the scoring mix involves both query-dependent and query-independent factors. Specifically, 60% of the total weight comes from how well the document matches the query. While the reputation field contributes 30%, and the inbound_links field makes up the remaining 10%.

curl https://api.lixiasearch.com/v1/indexes/$INDEX_ID/search \
  --header "Authorization: Bearer $ACCESS_TOKEN$" \
  --header "Content-Type: application/json" \
  --data @- << EOF
{
    "filters": [
        { "type": "field", "name": "body", "values": ["foobar"] },
        { "type": "field", "name": "title", "values": ["foobar"] }
    ],
    "offset": 0,
    "selectFields": [
        {
            "name": "id",
            "value": true
        },
         {
            "name": "title",
            "value": true
        }
    ],
    "scoring": [
        {"type": "words", "weight": 6},
        {"type": "feature", "name": "reputation", "weight": 3},
        {"type": "feature", "name": "inbound_links", "weight": 1}
    ]
}
EOF

Make sure you replace $ACCESS_TOKEN with your actual access token and $INDEX_ID$ with the appropriate index id.

Response Body

{
    "hasMoreDocuments": boolean,
    "hits": [
        {
            "fields": [
                {
                    "name": "string",
                    "snippet": "string" | null,
                    "value": "string | null
                },
                ...
            ]
        },
        ...
    ]
}

• hasMoreDocuments: Indicates whether there are additional pages of results.
• hits: A list of hits, where each hit corresponds to a document.
  • fields: The fields associated with a hit.
    • name: The name of the field.
    • snippet: A snippet of the field, or undefined if not requested.
    • value: The value of the field, or undefined if not requested.