Quick-start
Edit pageThis guide takes you through installing Xapiand, starting a node, and using it to index and search documents. It takes a few minutes.
Installing and Running
Section titled “Installing and Running”Using Docker
Section titled “Using Docker”# Run from Docker with *very-very-very* verbose output:docker run -p 8880:8880 --rm ghcr.io/kronuz/xapiand:latest -vvvvThe 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.
Using Homebrew under macOS
Section titled “Using Homebrew under macOS”# Install with Homebrew:brew install Kronuz/tap/xapiand
# Run in foreground with *very-very-very* verbose output:xapiand -vvvvYou can also check the Installation section for more details.
The node
Section titled “The node”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.
Indexing
Section titled “Indexing”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.
What a write answers
Section titled “What a write answers”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.
Searching
Section titled “Searching”Now, let’s retrieve the information we just added by GETting it:
GET /twitter/user/KronuzGET /twitter/tweet/1GET /twitter/tweet/2A 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:KronuzThe same search with COUNT returns only the number of matches:
COUNT /twitter/tweet/?q=user:KronuzYou can find out more in the Data Exploration section.