Hello world tutorial


April 5, 2019

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

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" \

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.

Back to developer docs


Aito Intelligence Oy

Kaivokatu 10 A, 8th floor

00100 Helsinki


VAT ID FI28756352

See map

470 Ramona St.

Palo Alto

CA 94301, USA

See map


COVID-19 situation has driven us all to work from homes, please connect with us online. Stay safe & play with data!

About usContact usJoin our Slack workspace

Follow us