Aito SDK

The Aito SDK consists of:

• schema: Data structure for the Aito Database Schema

• client: A versatile client to make requests to an Aito Database Instance

• v2: A client for the Aito v2 API

• client_request: Request objects used in AitoClient request so that you don’t have to worry about the Aito API endpoint

• client_response: Enriched response objects returned after executing a request with the AitoClient

• api: Different useful functions that uses an AitoClient object to interact with an Aito Database Instance

• DataFrameHandler: Utility to read, write, and convert a Pandas DataFrame in accordance to a Aito Table Schema

Note

We highly recommend you to take a look at the quickstart guide to uploading data if you haven’t already.

AitoSchema

Before uploading data into Aito, you need to create a table with a AitoTableSchema.

You can infer a table schema from a Pandas DataFrame with infer_from_pandas_data_frame().

You can also create a table schema column-by-column and infer the AitoColumnTypeSchema with infer_from_samples().

AitoClient

The AitoClient offers different functions to send a Request object to your Aito instance.

• Make a request: request()

• Make a request asynchronously using AIOHTTP ClientSession: async_request()

• Bounded asynchronous request with asyncio semaphore: bounded_async_request()

• Make multiple requests asynchronously: batch_requests()

AitoClientV2

The AitoClientV2 talks to the v2 API. It is a separate class from the v1 AitoClient rather than a flag on it, because the two APIs return genuinely different response shapes — the reasoning is written up in docs/v2-client-design.md.

from aito.client.v2 import AitoClientV2

client = AitoClientV2(instance_url, api_key)

prediction = client.predict(
    from_table='invoices', where={'vendor': 'Elenia Oy'}, predict='gl_code')
print(prediction.first.value, prediction.first.probability)

Querying:

• Predict a field’s value: predict()

• Retrieve rows: search()

• Rank values by a goal: recommend()

• Find statistical relationships: relate()

• Match a link field’s candidates against evidence: match()

• Estimate a numeric field: estimate()

• Aggregate: aggregate()

• Evaluate prediction quality: evaluate()

• Anything else, via the universal _query endpoint: query()

Note

The named methods post to v2’s enforced named endpoints, which validate that the body matches the operation. A mismatch is a 400 naming the endpoint that wants that body, rather than a query that silently does something else.

Manipulating the database:

Note

These operations require the client to be setup with the READ-WRITE API key

• Create a collection: create_collection()

• Delete a collection: delete_collection()

• Upload batches of entries: upload_entries()

• Rebuild the index after a bulk load: optimize()

• Branch an environment: branch_env()

Errors carry a machine-readable code, so you branch on the code rather than on the text of the message:

from aito.client.v2 import AitoV2Error

try:
    client.delete_collection('invoices')
except AitoV2Error as err:
    if not err.is_not_found:   # a 404 here is the ordinary "drop if exists" case
        raise

Responses carry the engine’s non-fatal warnings, which are the only in-band signal that the server answered a slightly different query than the one you sent:

res = client.query({'from': 'invoices', 'where': {'no_such_column': 'x'}})
for warning in res.warnings:
    print(warning.code, warning.message)

# or make it a hard failure:
strict = AitoClientV2(instance_url, api_key, on_warning='raise')

Aito reports its own server-side processing time in the x-aitoai-response-time header, which is what an application should surface rather than the round trip. The parsed body does not carry it, so pass on_response:

timings = []
client = AitoClientV2(instance_url, api_key,
                      on_response=lambda resp, path: timings.append(
                          (path, float(resp.headers['x-aitoai-response-time']))))

A complete runnable example — create a collection, load it, predict, explain, evaluate, drop it — is in examples/v2_quickstart.py.

AitoAPI

aito.api module offers different functions that takes a Aito Client object as the first argument

• Manipulate the database:

  Note

  These operations require the client to be setup with the READ-WRITE API key

  • Create a table: create_table()

  • Delete a table: delete_table()

  • Create the database: create_database()

  • Delete the database: delete_database()

  • Copy a table: copy_table()

  • Rename a table: rename_table()

• Upload the data:

  Note

  These operations require the client to be setup with the READ-WRITE API key

  • Upload a binary file object to a table: upload_binary_file()

  • Upload a file to a table: upload_file()

  • Upload batches of entries to a table: upload_entries()

  • Optimize a table after uploading the data: optimize_table()

• Get information about the database:

  • Get the instance version: get_version()

  • Check if a table exists in the instance: check_table_exists()

  • Get a list of existing tables in the instance: get_existing_tables()

  • Get a table schema: get_table_schema()

  • Find the number of entries in a table: get_table_size()

  • Get the database schema: get_database_schema()

• Querying:

  • Query entries of a table: query_entries()

  • Query all entries of a table: query_all_entries()

  • Download a table: download_table()

  • Make a job request (for query that takes longer than 30 seconds): job_request()

  • Make a job request step by step: create_job(), get_job_status(), get_job_result()

Troubleshooting

The easiest way to troubleshoot the Aito SDK is by enabling the debug logging. You can enable the debug logging by:

import logging

logging.basicConfig(level=logging.DEBUG)