Getting Started

Welcome to the Lixia Search API's Getting Started Guide! This step-by-step tutorial is designed to guide you through the process of searching within documents. We'll show you how to create an index, how to add documents to it and how to search within it.

Understanding Your Documents

Before diving in, let's acquaint ourselves with the three sample documents we'll be using. Each document consists of three fields: id, title, and body. The id serves as a unique identifier (primary key), while the title and body are text-based fields that we'll search within.

Document 1

id: 1
title: Town's Basketball Team Scores Championship Win
body: In an exhilarating match, the local basketball team secured a championship victory, showcasing exceptional teamwork and skill. The win not only brought pride to the community but also underscored the positive impact of sports in fostering unity and camaraderie among residents.

Document 2

id: 2
title: Students Showcase Innovation at School Science Fair
body: The recent school science fair showcased impressive projects, ranging from eco-friendly inventions to scientific experiments. The event celebrated the creativity and innovation of students, inspiring a passion for learning and exploration within the school community.

Document 3

id: 3
title: Local Gym Promotes Health with Fitness Challenge
body: A local gym is encouraging community well-being by organizing a fitness challenge for residents. Participants engage in various activities promoting a healthy lifestyle, fostering a sense of community and emphasizing the importance of physical well-being.

Visit https://dashboard.lixiasearch.com and sign in with your credentials. If you don't have an account yet, go to https://dashboard.lixiasearch.com/sign-up.

Copy the Account ID from the dashboard; we'll need it for the next steps.

You can export it in your terminal:

export ACCOUNT_ID=<your-account-id>

Step 2: Create an Access Token

Navigate to the Access Tokens section in the dashboard, click on Create Access Token, and generate an access token with "Read and Write" access. Copy the access token; it will be used in subsequent steps.

You can export it in your terminal:

export ACCESS_TOKEN=<your-access-token>

Step 3: Create an Index

Before we can add documents, we need to create an index. There are three things to know about indexes.

An index is a collection of documents. We can add, update and remove documents from indexes. And more importantly, we can search documents within an index.
An index has a schema. It defines the fields and their corresponding types within the documents.
One of the field in the schema is special. It's the primary key. It's the field that is used to uniquely identify a document. Only one document can exist per primary key value.

In this tutorial, we'll name the primary key id. And we'll use two text-based fields: title and body.

With the token you created in the previous step, let's create an index with the Create Index endpoint.

Request:

curl https://api.lixiasearch.com/v1/indexes \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data @- <<EOF
{
  "accountId": "$ACCOUNT_ID",
  "fields": [
    {"name": "id", "primaryKey": true, "type": "int64"},
    {"name": "body", "type": "text"},
    {"name": "title", "type": "text"}
  ],
  "name": "my_index"
}
EOF

Response:

{
    "id": <index id>
}

Replace $ACCESS_TOKEN with your access token and $ACCOUNT_ID with your account ID obtained in Step 1.

The response body is the index id. Copy it; it will be used in subsequent steps.

You can export it in your terminal:

export INDEX_ID=<your-index-id>

So we've created a schema with three fields:

id: has int64 type and is the primary key
title: has text type
body: has text type

As we've configured the type of the title and body fields as text, we'll have the capability to perform full-text searches within these fields.

Step 4: Add Documents to Your Index

Now the index is ready, let's add documents to it using the Add or Update Document endpoint:

Document 1:

curl https://api.lixiasearch.com/v1/indexes/$INDEX_ID/documents \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    --header "Content-Type: application/json" \
    --data @- << EOF
{
    "fields": [
        {"name": "body", "value": "In an exhilarating match, the local basketball team secured a championship victory, showcasing exceptional teamwork and skill. The win not only brought pride to the community but also underscored the positive impact of sports in fostering unity and camaraderie among residents."},
        {"name": "id", "value": 1},
        {"name": "title", "value": "Town's Basketball Team Scores Championship Win"}
    ]
}
EOF

Document 2:

curl https://api.lixiasearch.com/v1/indexes/$INDEX_ID/documents \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    --header "Content-Type: application/json" \
    --data @- << EOF
{
    "fields": [
        {"name": "body", "value": "The recent school science fair showcased impressive projects, ranging from eco-friendly inventions to scientific experiments. The event celebrated the creativity and innovation of students, inspiring a passion for learning and exploration within the school community."},
        {"name": "id", "value": 2},
        {"name": "title", "value": "Students Showcase Innovation at School Science Fair"}
    ]
}
EOF

Document 3:

curl https://api.lixiasearch.com/v1/indexes/$INDEX_ID/documents \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    --header "Content-Type: application/json" \
    --data @- << EOF
{
    "fields": [
        {"name": "body", "value": "A local gym is encouraging community well-being by organizing a fitness challenge for residents. Participants engage in various activities promoting a healthy lifestyle, fostering a sense of community and emphasizing the importance of physical well-being."},
        {"name": "id", "value": 3},
        {"name": "title", "value": "Local Gym Promotes Health with Fitness Challenge"}
    ]
}
EOF

Step 5: Search Within Your Documents

With documents in the index, utilize the Search endpoint to perform searches.

The search endpoint is broken down into a few components.

It requires us to define the filters, determining the values by which we will filter the documents. This is managed through the filter field. Subsequently, we need to specify the fields to be returned, controlled by the selectFields field.

For instance, if we want to retrieve all documents containing the word "community" in either their title or body, and we only want to display the id and title of each document:

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": ["community"] },
        { "type": "field", "name": "title", "values": ["community"] }
    ],
    "offset": 0,
    "selectFields": [
        {
            "name": "id",
            "value": true
        },
        {
            "name": "title",
            "value": true
        }
    ]
}
EOF

Response:

{
    "hasMoreDocuments": false,
    "hits": [
        {
            "fields": [
                {
                    "name": "id",
                    "value": 3
                },
                {
                    "name": "title",
                    "value": "Local Gym Promotes Health with Fitness Challenge"
                }
            ]
        },
        {
            "fields": [
                {
                    "name": "id",
                    "value": 2
                },
                {
                    "name": "title",
                    "value": "Students Showcase Innovation at School Science Fair"
                }
            ]
        },
        {
            "fields": [
                {
                    "name": "id",
                    "value": 1
                },
                {
                    "name": "title",
                    "value": "Town's Basketball Team Scores Championship Win"
                }
            ]
        }
    ]
}

Note that the hits are oredered based on their relevance, with the most pertinent one being presented first.

A notable feature of Lixia Search is its capability to provide a highlighted snippet for a field. Lixia Search will automatically find the best snippet based on the query. Lixia Search will also guarantee that the snippet can be no longer than a certain limit. For example, here's how to get a snippet of the body, limited to 200 characters, for the query "community":

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": ["community"] },
        { "type": "field", "name": "title", "values": ["community"] }
    ],
    "offset": 0,
    "selectFields": [
        {
            "name": "id",
            "value": true
        },
         {
            "name": "title",
            "value": true
        },
        {
            "name": "body",
            "snippet": { "escapeHtml": true, "length": 200 },
            "value": false
        }
    ]
}
EOF

Response:

{
    "hasMoreDocuments": false,
    "hits": [
        {
            "fields": [
                {
                    "name": "id",
                    "value": 3
                },
                {
                    "name": "title",
                    "value": "Local Gym Promotes Health with Fitness Challenge"
                },
                {
                    "name": "body",
                    "snippet": "A local gym is encouraging <em>community</em> well-being by organizing a fitness challenge for residents. Participants engage in various activities promoting a healthy lifestyle, fostering a sense of ..."
                }
            ]
        },
        {
            "fields": [
                {
                    "name": "id",
                    "snippet": null,
                    "value": 2
                },
                {
                    "name": "title",
                    "snippet": null,
                    "value": "Students Showcase Innovation at School Science Fair"
                },
                {
                    "name": "body",
                    "snippet": "from eco-friendly inventions to scientific experiments. The event celebrated the creativity and innovation of students, inspiring a passion for learning and exploration within the school <em>community</em> ..."
                }
            ]
        },
        {
            "fields": [
                {
                    "name": "id",
                    "value": 1
                },
                {
                    "name": "title",
                    "value": "Town's Basketball Team Scores Championship Win"
                },
                {
                    "name": "body",
                    "snippet": "victory, showcasing exceptional teamwork and skill. The win not only brought pride to the <em>community</em> but also underscored the positive impact of sports in fostering unity and camaraderie among ..."
                }
            ]
        }
    ]
}

That concludes this tutorial! If you have any questions, please reach out to us at support@lixiasearch.com.

Getting Started

Understanding Your Documents

Step 1: Sign in to the Dashboard

Step 2: Create an Access Token

Step 3: Create an Index

Step 4: Add Documents to Your Index

Step 5: Search Within Your Documents