Tutorial: Python

Prerequisites

  1. Install Ibis Birdbrain

Overview

You can use Ibis Birdbrain in Python.

Setup the bot

First, import relevant modules:

import ibis

from ibis_birdbrain import Bot

Set Ibis interactive mode:

ibis.options.interactive = True

Create an Ibis connection

Create an Ibis connection to your database:

Warning

We’ll create a demo database for this tutorial.

con = ibis.connect("duckdb://penguins.ddb")
con.create_table(
    "penguins", ibis.examples.penguins.fetch().to_pyarrow(), overwrite=True
)
con = ibis.connect("duckdb://penguins.ddb")
con.list_tables()
INFO:pins.cache:cache file: /Users/cody/Library/Caches/pins-py/gcs_332a30997e141da0e08f15fbfae8b3c3ec90463922d117a96fa3b1bef85a2a4c/penguins/20230905T090411Z-9aae2/data.txt
INFO:pins.cache:cache file: /Users/cody/Library/Caches/pins-py/gcs_332a30997e141da0e08f15fbfae8b3c3ec90463922d117a96fa3b1bef85a2a4c/penguins/20230905T090411Z-9aae2/penguins.csv.gz
['penguins']

Create the bot

You’ll create the bot by passing in the connection:

Tip

For increased accuracy, you should also pass in a data_description containing information about the dataset. This could be fetched from the database itself, manually created, or otherwise obtained.

You should not include table names and schemas – this will be inferred automatically.

bot = Bot(con=con, data_description="the Palmer Penguins dataset")
bot
INFO:root:Bot birdbrain initialized...
<ibis_birdbrain.bot.Bot at 0x292262c10>

Test the bot

You can ask the bot questions:

res = bot("""give me the counts of penguins by species and island from highest
to lowest""")
res
INFO:root:Bot birdbrain called with text: give me the counts of penguins by species and island from highest
to lowest
INFO:root:Selected flow: data
INFO:root:Executing the data flow
INFO:root:Text to SQL task
INFO:httpx:HTTP Request: POST https://birdbrain-eh.openai.azure.com/openai/deployments/gpt-4-turbo/chat/completions?api-version=2023-12-01-preview "HTTP/1.1 200 OK"
INFO:root:Executing the SQL task














To: user
From: birdbrain
Subject: give me the counts of pengu...
Sent at: 2024-03-05 12:18:51.951695
Message: 67c02541-9406-4de5-b99e-21cc5dc8d3c5
Ibis Birdbrain has attached the results.
Attachments:
CodeAttachment
    **guid**: e2152990-296e-4b92-a159-05af61b5334a
    **time**: 2024-03-05 12:18:51.949484
    **name**: None
    **desc**: None
    **language**: sql
    **code**:
SELECT species, island, COUNT(*) AS count
FROM penguins
GROUP BY species, island
ORDER BY COUNT(*) DESC
TableAttachment
    **guid**: e6acb87c-b4ca-4fa7-8292-638d3fc0b6e8
    **time**: 2024-03-05 12:18:51.951600
    **name**: None
    **desc**: 
ibis.Schema {
  species  string
  island   string
  count    int64
}
                **table**:
┏━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┓
┃ species   ┃ island    ┃ count ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━┩
│ string    │ string    │ int64 │
├───────────┼───────────┼───────┤
│ Gentoo    │ Biscoe    │   124 │
│ Chinstrap │ Dream     │    68 │
│ Adelie    │ Dream     │    56 │
│ Adelie    │ Torgersen │    52 │
│ Adelie    │ Biscoe    │    44 │
└───────────┴───────────┴───────┘












Get attachments


You can get the table from the attachment:




t = res.attachments[-1].open()
t




┏━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┓
┃ species   ┃ island    ┃ count ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━┩
│ string    │ string    │ int64 │
├───────────┼───────────┼───────┤
│ Gentoo    │ Biscoe    │   124 │
│ Chinstrap │ Dream     │    68 │
│ Adelie    │ Dream     │    56 │
│ Adelie    │ Torgersen │    52 │
│ Adelie    │ Biscoe    │    44 │
└───────────┴───────────┴───────┘







And do whatever you want with it:




t.order_by(ibis._["count"].asc())




┏━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┓
┃ species   ┃ island    ┃ count ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━┩
│ string    │ string    │ int64 │
├───────────┼───────────┼───────┤
│ Adelie    │ Biscoe    │    44 │
│ Adelie    │ Torgersen │    52 │
│ Adelie    │ Dream     │    56 │
│ Chinstrap │ Dream     │    68 │
│ Gentoo    │ Biscoe    │   124 │
└───────────┴───────────┴───────┘













Next steps


Explore some data with Ibis Birdbrain and let us know how it goes!






 Back to top