Skip to content

Commit 8bcb85b

Browse files
committed
docs: add backend creation examples to table hierarchy explanation
1 parent cc9d22d commit 8bcb85b

File tree

1 file changed

+52
-0
lines changed

1 file changed

+52
-0
lines changed

docs/concepts/backend-table-hierarchy.qmd

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,58 @@ In other words, the full specification of a table in Ibis is either
1414
- `catalog.database.table`
1515
- `database.table`
1616

17+
For example, to access the `t` table in the `d` database in the `c` catalog,
18+
you would do `conn.table("t", database=("c", "d"))`.
19+
See the [Backend.table() documentation](backends/duckdb.qmd#ibis.backends.duckdb.Backend.table)
20+
for more details.
21+
22+
We use this common terminology in the API of every Backend, **once constructed**.
23+
However, when you initially **create** a Backend, you will use the
24+
backend-specific terminology. We made this design decision so that
25+
26+
- You can use the same API for constructing a Backend as for constructing the Backend's
27+
native connection.
28+
- But, once you have the Backend, you can use the ibis common terminology
29+
no matter which Backend you are using,
30+
which makes it so that if you want to switch from one Backend to another,
31+
you only have to change your code that **creates** the connection,
32+
not the code that **uses** the connection.
33+
34+
For example, when connecting to a PostgreSQL database using the native
35+
`psycopg` driver, you would use the following code:
36+
37+
```python
38+
psycopg.connect(
39+
user="me",
40+
password="supersecret",
41+
host="abc.com",
42+
port=5432,
43+
dbname="my_database",
44+
options="-csearch_path=my_schema",
45+
)
46+
```
47+
48+
In ibis, you would use the following code (note how it is analogous to the above)
49+
50+
```python
51+
conn = ibis.postgres.connect(
52+
user="me",
53+
password="supersecret",
54+
host="abc.com",
55+
port=5432,
56+
database="my_database",
57+
schema="my_schema",
58+
)
59+
```
60+
61+
AFTER you have constructed the Backend however, now use the common terminology:
62+
63+
```python
64+
conn.table("my_table", database=("my_database", "my_schema"))
65+
conn.list_catalogs() # results in something like ["my_database"]
66+
conn.list_databases() # results in ["my_schema"]
67+
```
68+
1769
Below is a table with the terminology used by each backend for the two levels of
1870
hierarchy. This is provided as a reference, note that when using Ibis, we will
1971
use the terms `catalog` and `database` and map them onto the appropriate fields.

0 commit comments

Comments
 (0)