===========
Hello Crate
===========

.. highlight:: sh

To get started let's have a quick look on how Crate can be accessed
via the bare HTTP-Endpoints. This tutorial uses the Curl_ command-line
utility to do the requests.

To check if Crate is running, we can do a GET on the root, which
displays basic system information::

    sh$ curl -sS '127.0.0.1:44200/?pretty=1'
    {
      "ok" : true,
      "status" : 200,
      "name" : "crate",
      "version" : {
        "number" : "...",
        "build_hash" : "...",
        "build_timestamp" : "...",
        "build_snapshot" : ...,
        "es_version" : "...",
        "lucene_version" : "..."
      }
    }


.. note::

 The ``pretty`` query parameter used above tells Crate to pretty print
 results. This works for every endpoint.

In this guide we want to create a database for quotes. Let's create
the index and the ``quote`` type, which will contain information about
the author of the quote and the quote itself::

    sh$ curl -sSX POST 'http://127.0.0.1:44200/_sql?pretty=1&refresh=true' -d @- <<EOF
    ... {
    ... "stmt": "create table quotes (author string, content string)"
    ... }
    ... EOF
    {
      "cols" : [ ],
      "rows" : [ ],
      "rowcount" : 0,
      "duration" : ...
    }

Now we can add the first quote to the database::

    sh$ curl -sSX POST '127.0.0.1:44200/_sql?pretty=1&refresh=true' -d @- <<EOF
    ... {
    ... "stmt": "insert into quotes values('Me', 'Hello Crate!')"
    ... }
    ... EOF
    {
      "cols" : [ ],
      "rows" : [ ],
      "rowcount" : 1,
      "duration" : ...
    }

Refresh in order to make the result immediately visible in subsequent queries::

    sh$ curl -sSX POST '127.0.0.1:44200/quotes/_refresh?pretty=1'
    {
      "ok" : true,
      "_shards" : {
        "total" : 10,
        "successful" : 5,
        "failed" : 0
      }
    }


We can now view what we have just inserted like this::

    sh$ curl -sSX POST '127.0.0.1:44200/_sql?pretty=1' -d @- <<EOF
    ... {
    ... "stmt": "select author, content from quotes order by author"
    ... }
    ... EOF
    {
      "cols" : [ "author", "content" ],
      "rows" : [ [ "Me", "Hello Crate!" ] ],
      "rowcount" : 1,
      "duration" : ...
    }

Let's add another quote::

    sh$ curl -sSX POST '127.0.0.1:44200/_sql?pretty=1&refresh=true' -d @- <<EOF
    ... {
    ... "stmt": "insert into quotes values('Ford', 'Don''t panic... don''t panic...')"
    ... }
    ... EOF
    {
      "cols" : [ ],
      "rows" : [ ],
      "rowcount" : 1,
      "duration" : ...
    }

Refresh again::

    sh$ curl -sSX POST '127.0.0.1:44200/quotes/_refresh?pretty=1'
    {
      "ok" : true,
      "_shards" : {
        "total" : 10,
        "successful" : 5,
        "failed" : 0
      }
    }

Looking up only Ford's quotes::

    sh$ curl -sSX POST '127.0.0.1:44200/_sql?pretty=1' -d @- <<EOF
    ... {
    ... "stmt": "select content from quotes where author='Ford'"
    ... }
    ... EOF
    {
      "cols" : [ "content" ],
      "rows" : [ [ "Don't panic... don't panic..." ] ],
      "rowcount" : 1,
      "duration" : ...
    }


.. _Curl: http://curl.haxx.se/
.. _SQL: https://en.wikipedia.org/wiki/SQL


