Skip to content

feat: add :get-objects and :get-schema #34

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
serramatutu wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: add :get-objects and :get-schema #34

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,30 @@ Execute SQL queries:
└─────────┴───────────┴────────────────┴───────────────┴───────────────────┴─────────────┴────────┴──────┘
```

Inspect the database with colon-prefixed commands instead of SQL:

```
> :get-objects warehouse.main.%
┌───────────┬───────────┬──────────┬────────────┐
│ catalog │ db_schema │ table │ table_type │
├───────────┼───────────┼──────────┼────────────┤
│ warehouse │ main │ adelie │ VIEW │
│ warehouse │ main │ penguins │ BASE TABLE │
└───────────┴───────────┴──────────┴────────────┘
> :get-schema penguins
┌────────────────┬─────────┬──────────┐
│ column │ type │ nullable │
├────────────────┼─────────┼──────────┤
│ species │ Utf8 │ true │
│ island │ Utf8 │ true │
│ bill_length_mm │ Float64 │ true │
│ body_mass_g │ Int32 │ true │
│ year │ Int32 │ true │
└────────────────┴─────────┴──────────┘
```

Type `:help` for the full list of commands.

### Non-interactive Usage

Execute a query directly and exit:
Expand Down
44 changes: 44 additions & 0 deletions docs/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,50 @@ The output format is inferred from the file extension:
| `.csv` | CSV |
| `.arrow`, `.ipc`| Arrow IPC |

## Commands

A line starting with `:` is a command instead of a SQL query. Commands work in the interactive shell and with [`--query`](/reference/#-query), [`--file`](/reference/#-file) and standard input.

| Command | Alias | Description |
|-----------------------------------------|-------|-----------------------------------|
| `:get-objects [<catalog.schema.table>]` | `:go` | List catalogs, schemas and tables |
| `:get-schema <catalog.schema.table>` | `:gs` | Show the columns of a table |
| `:help` | `:h` | List the commands |
| `:quit` | `:q` | Exit databow |

`:get-objects` calls the ADBC `GetObjects` method, so it works the same way on every driver. Without an identifier it lists every catalog, schema and table the connection exposes. The parts of the identifier are ADBC search patterns, where `%` and `_` are wildcards:

```console
> :get-objects warehouse.main.%
┌───────────┬───────────┬──────────┬────────────┐
│ catalog │ db_schema │ table │ table_type │
├───────────┼───────────┼──────────┼────────────┤
│ warehouse │ main │ adelie │ VIEW │
│ warehouse │ main │ penguins │ BASE TABLE │
└───────────┴───────────┴──────────┴────────────┘
```

`:get-schema` calls `GetTableSchema` and shows the Arrow schema of one table. The table name must match exactly:

```console
> :get-schema penguins
┌────────────────┬─────────┬──────────┐
│ column │ type │ nullable │
├────────────────┼─────────┼──────────┤
│ species │ Utf8 │ true │
│ island │ Utf8 │ true │
│ bill_length_mm │ Float64 │ true │
│ body_mass_g │ Int32 │ true │
│ year │ Int32 │ true │
└────────────────┴─────────┴──────────┘
```

Both commands produce a table like any query, so [`--mode`](/reference/#-mode) and [`--output`](/reference/#-output) work:

```sh
databow --profile warehouse --query ":get-objects" --output objects.json
```

## --help

Print the help message
Expand Down
27 changes: 27 additions & 0 deletions docs/tutorial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,33 @@ $ databow --profile warehouse --mode ascii-markdown
| Adelie | 152 |
```

### Commands

A line starting with `:` is a command instead of a query. `:get-objects` lists catalogs, schemas and tables. `:get-schema` shows the columns of one table.

```console
$ databow --profile warehouse
> :get-objects warehouse.main.%
┌───────────┬───────────┬──────────┬────────────┐
│ catalog │ db_schema │ table │ table_type │
├───────────┼───────────┼──────────┼────────────┤
│ warehouse │ main │ adelie │ VIEW │
│ warehouse │ main │ penguins │ BASE TABLE │
└───────────┴───────────┴──────────┴────────────┘
> :get-schema penguins
┌────────────────┬─────────┬──────────┐
│ column │ type │ nullable │
├────────────────┼─────────┼──────────┤
│ species │ Utf8 │ true │
│ island │ Utf8 │ true │
│ bill_length_mm │ Float64 │ true │
│ body_mass_g │ Int32 │ true │
│ year │ Int32 │ true │
└────────────────┴─────────┴──────────┘
```

Type `:help` for the full list, and `:quit` to exit. The [commands reference](/reference/#commands) documents each one.

## Non-interactive Usage

The [`--query` argument](/reference/#-query) can be used to execute a query and exit:
Expand Down
Loading