API Access

API Access

To integrate Defog in your application, you can use the Defog API via either a RESTful API, or a Python client. This page assumes that you have used the Quick Start guide to extract metadata from Defog, and link your API key to it.

REST API

Generate SQL query, given a text question

ENDPOINT: https://api.defog.ai/generate_query_chat

PARAMETERS:

  • api_key: Your API key. This is used to verify your identity
  • db_type: The type of database you are querying. This must be one of:
    • bigquery
    • databricks
    • mysql
    • postgres
    • redshift
    • snowflake
    • sqlite
    • sqlserver
  • question: The question you want to ask Defog
  • previous_context: (optional) The previous context of the conversation. This is used to maintain context across multiple questions in a conversation. This is an array of strings in the format ["previous question", "previous_sql"]

(more advanced parameters to be added later)

EXAMPLE:

curl -X POST https://api.defog.ai/generate_query_chat \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "db_type": "postgres",
    "question": "What is the average revenue by region?",
  }'

RESPONSE:

{
  "ran_successfully": true,
  "sql": "SELECT region, AVG(revenue) FROM sales GROUP BY region",
  "previous_context": ["What is the average revenue by region?", "SELECT region, AVG(revenue) FROM sales GROUP BY region"]
}

The sql field contains the SQL query generated by Defog, and the previous_context can be used in the next query to maintain context.

Python Client

You can also use Defog's Python client instead of the API. This client library is a wrapper around the API, but also executes the SQL query on your database and returns the results.

To use the Python client, you can install it via pip:

pip install defog

Here is an example of how you can use the Python client:

from defog import Defog
defog = Defog(YOUR_API_KEY, db_type="YOUR_DB_TYPE", db_creds=YOUR_DB_CREDS)
# you only need to do this once. your api key, database credentials, and db_type will be saved in a config file in your home directory for future use
 
# if your db_type is postgres or redshift, then db_creds should be {"host": "YOUR_HOST", "port": YOUR_PORT, "database": "YOUR_DATABASE_NAME", "user": "YOUR_USERNAME", "password": "YOUR_PASSWORD"}
# if your db_type is mysql, then db_creds should be {"host": "YOUR_HOST", "database": "YOUR_DATABASE_NAME", "user": "YOUR_USERNAME", "password": "YOUR_PASSWORD"}
# if your database type is Snowflake, then db_creds should be {"account": "YOUR_ACCOUNT", "warehouse": "YOUR_WAREHOUSE", "user": "YOUR_USERNAME", "password": "YOUR_PASSWORD"}
# if your database type is Databricks, then db_creds should be {"server_hostname": "YOUR_SERVER_HOSTNAME", "access_token": "YOUR_ACCESS_TOKEN", "http_path": "YOUR_HTTP_PATH"}
# if your database type is SQLServer, then db_creds should be {"server": "YOUR_SERVER", "database": "YOUR_DATABASE", "user": "YOUR_USERNAME", "password": "YOUR_PASSWORD"}
# if your database type is Bigquery, then db_creds should be {"json_key_path": "/path/to/your/service_accoun_key.json"}
 
# defog = Defog()
 
defog.run_query(
  question="What is the average revenue by region?",
  previous_context=None
)

The run_query method generates the SQL query and executes it on your database. The previous_context parameter can be used to maintain context across multiple questions in a conversation.

Querying Your DataDocker Deployment