Hello world tutorial

This tutorial is meant to be the simplest possible example of how to take Aito into use. It covers:

• Creating a schema
• Importing your data into Aito
• Sending a simple query

You need to have an Aito environment and a read-write API key for it. If you don't have an environment, we're happy to create a free environment for you.

We're using curl for doing HTTP requests in the tutorial, because it's installed by default in most *nix environments. You can also use other tools, we have a few recommendations in our Sending requests article.

Step 1: Create a schema

See Create database schema in our API docs for more details.

Aito organises data much like traditional SQL databases do – in tables which have schemas. This makes each row in table consistent and also allows Aito to better analyse the data.

Let's create a local file called schema.json:

{
  "schema": {
    "messages": {
      "type": "table",
      "columns": {
        "content": { "type": "Text" }
      }
    }
  }
}

In the schema, we define a table called messages, which has one column:

Next, open a terminal and browse to the directory where schema.json is located. Set the environment and API key as an environment variable with:

export AITO_ENVIRONMENT=my-environment
export AITO_KEY=YOUR_API_KEY_HERE

Then you can just copy paste the commands from the rest of the tutorial to your terminal. AITO_INSTANCE_URL has the form of: my-environment.aito.app.

Now let's send the request to create the database schema:

curl -X PUT "https://$AITO_INSTANCE_URL/api/v1/schema" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d@schema.json

Step 2: Import your data

The database now has a single table in its schema and we can upload rows to it. Each row in the data needs to be valid against the given schema.

Let's send a list of rows to our messages table:

curl -X POST \
  https://$AITO_INSTANCE_URL/api/v1/data/messages/batch \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '
  [
    { "content": "Hello world" },
    { "content": "A second message" }
  ]'

Now we've added two rows to the messages table.

To upload larger sets of data, see file upload API reference. You can find a bash script for file upload at our tools repository. See the upload-file.sh script.

Step 3: Send a query

Let's simply ask for all rows in the messages table. For this we're using the Search -query:

curl -X POST \
  https://$AITO_INSTANCE_URL/api/v1/_search \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "from": "messages"
  }'

You should see the following response:

{
  "offset": 0,
  "total": 2,
  "hits": [
    { "content": "Hello world" },
    { "content": "A second message" }
  ]
}

That's it! We also recommend checking out the API reference documentation to learn more about the powerful query language.