Skip to content

Quick-start

Edit page

This guide takes you through installing Xapiand, starting a node, and using it to index and search documents. It takes a few minutes.


Terminal window
# Run from Docker with *very-very-very* verbose output:
docker run -p 8880:8880 --rm ghcr.io/kronuz/xapiand:latest -vvvv

The container keeps its data in /var/db/xapiand. Mount a volume there (-v xapiand-data:/var/db/xapiand) to keep the indexes after the container stops.

Terminal window
# Install with Homebrew:
brew install Kronuz/tap/xapiand
# Run in foreground with *very-very-very* verbose output:
xapiand -vvvv

You can also check the Installation section for more details.

A single node serves the whole REST API over HTTP on port 8880 (--port sets another). It keeps every index under its data directory (-D, --database; <prefix>/var/db/xapiand unless given), and it logs Node <name> is Ready to Rock! when it is ready to serve. Stop it with Ctrl-C (SIGINT) or SIGTERM: it finishes the requests in flight, commits and closes its indexes, and exits (see Stopping the node).

Ask the node about itself:

GET /

The answer carries the node’s name, the server and versions it runs, the options it was started with, and its state.


Let’s index some twitter like information. In PUT /twitter/user/Kronuz, the path twitter/user names the index and Kronuz is the document ID. Writing to an index that does not exist creates it, so we create a twitter user and add some tweets, each kind in its own index (twitter/user and twitter/tweet):

PUT /twitter/user/Kronuz
{
"name": "Germán Méndez Bravo"
}
PUT /twitter/tweet/1
{
"user": "Kronuz",
"postDate": "2016-11-15T13:12:00",
"message": "Trying out Xapiand, so far, so good... so what!"
}
PUT /twitter/tweet/2
{
"user": "Kronuz",
"postDate": "2016-10-15T10:31:18",
"message": "Another tweet, will it be indexed?"
}

You can dig a little deeper in the Data Manipulation section.

A node started without -vvvv does not echo what it stored: a PUT with an ID answers 204 No Content with an empty body.

PUT /twitter/user/Quiet
{
"name": "Quiet Coder"
}

A POST to the index, which has no ID, answers 201 Created with the new document’s path in the Location header:

POST /twitter/user/
{
"name": "Anonymous Coder"
}

With echo on, a write answers 200 OK with the document, its _id and its _version. Turn it on for a node (--echo, or -vvvv) or per request (?echo); ?echo=false turns it off for one request. The examples in this documentation run with echo on, so the responses they show carry the document.


Now, let’s retrieve the information we just added by GETting it:

GET /twitter/user/Kronuz
GET /twitter/tweet/1
GET /twitter/tweet/2

A write is visible to the next read once the node has answered it, so a search right after the PUT finds the document. Let’s find all the tweets that Kronuz posted:

SEARCH /twitter/tweet/?q=user:Kronuz

The same search with COUNT returns only the number of matches:

COUNT /twitter/tweet/?q=user:Kronuz

You can find out more in the Data Exploration section.