Skip to main content

Getting started

This walkthrough takes you from a newly created account to the first query run on your database.

1. Sign in to the panel​

Open app.datafala.com.br/login with the email and password that the Datafala team sent you.

2. Configure the LLM​

In Settings, in the LLM provider section, choose the provider and model, paste your key from the provider's account and click Test before saving. The key is stored encrypted and is only decrypted at the moment of the call.

Accepted providers: OpenAI, Anthropic, Gemini, Mistral, Groq, DeepSeek, xAI, OpenRouter and Cohere.

3. Register the schema​

On the Schema screen, choose the dialect (PostgreSQL, MySQL or Firebird) and paste the DDL of the tables the API may use. A CREATE TABLE with columns and foreign keys is enough; data is never sent.

How to generate the DDL without data:

# PostgreSQL
pg_dump --schema-only --no-owner --no-privileges \
  -t public.pedidos -t public.clientes -t public.produtos \
  "postgresql://usuario@host/banco" > schema.sql

# MySQL
mysqldump --no-data --skip-comments banco pedidos clientes produtos > schema.sql

For Firebird (2.5 or newer), use the isql that ships with the server. The -x option extracts only the metadata of all tables, without data:

# Linux / macOS
isql -x -user SYSDBA -ch UTF8 \
  localhost:/dados/banco.fdb -o schema.sql

# Windows
isql.exe -x -user SYSDBA -ch UTF8 ^
  localhost:C:\Dados\BANCO.FDB -o schema.sql

isql will ask for the password in the terminal. Do not include it in the command or in the metadata file.

Prefer a graphical tool? In FlameRobin, right-click the database and use Extract metadata. In IBExpert, use Tools → Extract Metadata and select only the metadata, without data.

The database must use SQL dialect 3, including on Firebird 2.5 (check with SHOW SQL DIALECT; in isql). DDL with SQL dialect 1 is rejected. isql does not filter tables: paste the whole file and hide in the panel what the API must not use. System tables and procedures, triggers, indexes, generators and permissions included in the file are ignored.

After importing, describe tables and columns with names that are not obvious and hide what the API must not use (for example CPF or password columns). Hidden tables and columns do not go into the prompt and are rejected by the SQL Guard.

4. Write the context and a few examples​

  • Context: business rules and glossary in free text ("a cancelled sale has status = 'C'", "revenue = sum of valor_total for non-cancelled sales").
  • Examples: question → SQL pairs that show the right way to query your database. Each example goes through the SQL Guard when it is saved.

Use the Playground in the panel to test questions before integrating.

5. Create an API key​

In Credentials, create a key for the integration. It has the format tsk_<prefix>_<secret> and is shown only once. Store it in your server's secrets vault. See Authentication.

6. Ask the first question​

export DATAFALA_API_KEY="tsk_1a2b3c4d_..."

curl -sS -X POST "https://app.datafala.com.br/v1/ask" \
  -H "Authorization: Bearer $DATAFALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How many orders were placed yesterday?",
    "end_user": "5f0c3a9e7b1d4e2f8a6c0b9d3e7f1a2c4b5d6e7f8091a2b3c4d5e6f708192a3b"
  }'

Response:

{
  "sql": "SELECT count(*) AS total FROM public.pedidos WHERE criado_em >= %(start)s AND criado_em < %(end)s",
  "params": { "start": "2026-10-22", "end": "2026-10-23" },
  "dialect": "postgres",
  "tables": ["public.pedidos"],
  "explanation": "Counts the orders created yesterday.",
  "locale": "en",
  "request_id": "req_0f3c9a7d2b6e4f1a8c5d0e9b7a6f3c21"
}

The end_user field opaquely identifies the person who asked. See End-user identifier to generate it correctly.

7. Run it on your database​

rows = readonly_conn.execute(answer["sql"], answer["params"]).fetchall()

Read Run the SQL before going to production: it explains the read-only user, the maximum time per query and how to convert the placeholders for drivers in other languages.