mirror of
https://github.com/simonw/dclient.git
synced 2026-07-24 09:54:32 +02:00
02dd3ae9ca- Update README.md with new commands summary and uv development workflow - Add docs/exploring.md covering databases, tables, schema, rows, get commands with filtering, sorting, pagination, and output format examples - Add docs/writing.md covering create-table, upsert, update, delete, drop - Update docs/queries.md with output format options (--csv, --tsv, --nl, --table) - Update docs/inserting.md with cross-references to upsert/update - Update docs/index.md toctree to include new pages - Regenerate all cog --help blocks with current command signatures https://claude.ai/code/session_01DoiJf9Gbvbw2asN9yvP6dx
347 lines
8.2 KiB
Markdown
347 lines
8.2 KiB
Markdown
# Exploring data
|
|
|
|
dclient provides several commands for exploring Datasette instances without writing SQL.
|
|
|
|
## Listing databases
|
|
|
|
Use `dclient databases` to list all databases on a Datasette instance:
|
|
|
|
```bash
|
|
dclient databases https://latest.datasette.io
|
|
```
|
|
|
|
Use `--table` for a formatted text table:
|
|
```bash
|
|
dclient databases https://latest.datasette.io --table
|
|
```
|
|
Output:
|
|
```
|
|
name path is_mutable
|
|
-------- -------- ----------
|
|
fixtures fixtures False
|
|
```
|
|
|
|
## Listing tables
|
|
|
|
Use `dclient tables` to list tables in a specific database:
|
|
|
|
```bash
|
|
dclient tables https://latest.datasette.io/fixtures
|
|
```
|
|
|
|
Use `--table` for formatted output:
|
|
```bash
|
|
dclient tables https://latest.datasette.io/fixtures --table
|
|
```
|
|
|
|
Use `--schema` to include the CREATE TABLE SQL for each table:
|
|
```bash
|
|
dclient tables https://latest.datasette.io/fixtures --schema
|
|
```
|
|
|
|
Use `--views` to include views in the output (hidden by default).
|
|
|
|
## Viewing schemas
|
|
|
|
Use `dclient schema` to show the SQL schema for a database or an individual table:
|
|
|
|
```bash
|
|
# Schema for all tables in a database
|
|
dclient schema https://latest.datasette.io/fixtures
|
|
|
|
# Schema for a specific table
|
|
dclient schema https://latest.datasette.io/fixtures/facetable
|
|
```
|
|
|
|
## Browsing rows
|
|
|
|
Use `dclient rows` to browse table data with filtering, sorting, and pagination — no SQL required:
|
|
|
|
```bash
|
|
dclient rows https://latest.datasette.io/fixtures/facetable --table
|
|
```
|
|
|
|
### Filtering
|
|
|
|
Use `-w` / `--where` to filter rows. Supports [Datasette filter operators](https://docs.datasette.io/en/stable/json_api.html#table-arguments) like `__gt`, `__contains`, `__exact`, etc.:
|
|
|
|
```bash
|
|
# Exact match
|
|
dclient rows https://example.com/db/dogs -w breed=Poodle
|
|
|
|
# Greater than
|
|
dclient rows https://example.com/db/dogs -w age__gt=4
|
|
|
|
# Multiple filters (AND)
|
|
dclient rows https://example.com/db/dogs -w age__gte=3 -w breed=Labrador
|
|
```
|
|
|
|
For raw SQL WHERE clauses, use `--where-sql`:
|
|
```bash
|
|
dclient rows https://example.com/db/dogs --where-sql "age > 3 and breed != 'Poodle'"
|
|
```
|
|
|
|
### Sorting
|
|
|
|
```bash
|
|
# Sort ascending
|
|
dclient rows https://example.com/db/dogs --sort name
|
|
|
|
# Sort descending
|
|
dclient rows https://example.com/db/dogs --sort-desc age
|
|
```
|
|
|
|
### Selecting columns
|
|
|
|
```bash
|
|
# Include only specific columns
|
|
dclient rows https://example.com/db/dogs --col name --col breed
|
|
|
|
# Exclude specific columns
|
|
dclient rows https://example.com/db/dogs --nocol id
|
|
```
|
|
|
|
### Full-text search
|
|
|
|
```bash
|
|
dclient rows https://example.com/db/articles --search "python tutorial"
|
|
```
|
|
|
|
### Faceting
|
|
|
|
```bash
|
|
dclient rows https://example.com/db/dogs --facet breed
|
|
```
|
|
Facet results are printed to stderr, with the rows on stdout.
|
|
|
|
### Pagination
|
|
|
|
By default, only the first page of results is returned. Use `--all` to fetch every page:
|
|
|
|
```bash
|
|
dclient rows https://example.com/db/dogs --all
|
|
```
|
|
|
|
Control page size with `--size` and limit total rows with `--limit`:
|
|
|
|
```bash
|
|
# 10 rows per page, max 50 rows total
|
|
dclient rows https://example.com/db/dogs --size 10 --limit 50
|
|
```
|
|
|
|
## Fetching a single row
|
|
|
|
Use `dclient get` to fetch a single row by its primary key:
|
|
|
|
```bash
|
|
dclient get https://latest.datasette.io/fixtures/facetable 1
|
|
```
|
|
Output:
|
|
```json
|
|
{
|
|
"pk": 1,
|
|
"created": "2019-01-14 08:00:00",
|
|
"planet_int": 1,
|
|
"on_earth": 1,
|
|
"state": "CA",
|
|
...
|
|
}
|
|
```
|
|
|
|
For compound primary keys, separate values with a comma:
|
|
```bash
|
|
dclient get https://example.com/db/compound_pk a,b
|
|
```
|
|
|
|
## Output formats
|
|
|
|
The `databases`, `tables`, `rows`, and `query` commands all support multiple output formats:
|
|
|
|
- `--json` — JSON (default)
|
|
- `--csv` — CSV
|
|
- `--tsv` — TSV
|
|
- `--nl` — Newline-delimited JSON
|
|
- `--table` — Formatted text table
|
|
|
|
```bash
|
|
dclient rows https://example.com/db/dogs --csv > dogs.csv
|
|
dclient rows https://example.com/db/dogs --table
|
|
```
|
|
|
|
## dclient databases --help
|
|
<!-- [[[cog
|
|
import cog
|
|
from dclient import cli
|
|
from click.testing import CliRunner
|
|
runner = CliRunner()
|
|
result = runner.invoke(cli.cli, ["databases", "--help"])
|
|
help = result.output.replace("Usage: cli", "Usage: dclient")
|
|
cog.out(
|
|
"```\n{}\n```".format(help)
|
|
)
|
|
]]] -->
|
|
```
|
|
Usage: dclient databases [OPTIONS] [URL_OR_ALIAS]
|
|
|
|
List databases on a Datasette instance
|
|
|
|
Example usage:
|
|
|
|
dclient databases https://latest.datasette.io
|
|
|
|
Options:
|
|
--token TEXT API token
|
|
-v, --verbose Verbose output
|
|
--csv Output as CSV
|
|
--tsv Output as TSV
|
|
--json Output as JSON (default)
|
|
--nl Output as newline-delimited JSON
|
|
--table Output as text table
|
|
--help Show this message and exit.
|
|
|
|
```
|
|
<!-- [[[end]]] -->
|
|
|
|
## dclient tables --help
|
|
<!-- [[[cog
|
|
import cog
|
|
from dclient import cli
|
|
from click.testing import CliRunner
|
|
runner = CliRunner()
|
|
result = runner.invoke(cli.cli, ["tables", "--help"])
|
|
help = result.output.replace("Usage: cli", "Usage: dclient")
|
|
cog.out(
|
|
"```\n{}\n```".format(help)
|
|
)
|
|
]]] -->
|
|
```
|
|
Usage: dclient tables [OPTIONS] [URL_OR_ALIAS]
|
|
|
|
List tables in a Datasette database
|
|
|
|
Example usage:
|
|
|
|
dclient tables https://latest.datasette.io/fixtures
|
|
|
|
Options:
|
|
--token TEXT API token
|
|
--views Include views
|
|
--schema Show CREATE TABLE SQL
|
|
-v, --verbose Verbose output
|
|
--csv Output as CSV
|
|
--tsv Output as TSV
|
|
--json Output as JSON (default)
|
|
--nl Output as newline-delimited JSON
|
|
--table Output as text table
|
|
--help Show this message and exit.
|
|
|
|
```
|
|
<!-- [[[end]]] -->
|
|
|
|
## dclient schema --help
|
|
<!-- [[[cog
|
|
import cog
|
|
from dclient import cli
|
|
from click.testing import CliRunner
|
|
runner = CliRunner()
|
|
result = runner.invoke(cli.cli, ["schema", "--help"])
|
|
help = result.output.replace("Usage: cli", "Usage: dclient")
|
|
cog.out(
|
|
"```\n{}\n```".format(help)
|
|
)
|
|
]]] -->
|
|
```
|
|
Usage: dclient schema [OPTIONS] [URL_OR_ALIAS]
|
|
|
|
Show the SQL schema for a database or table
|
|
|
|
Example usage:
|
|
|
|
dclient schema https://latest.datasette.io/fixtures
|
|
dclient schema https://latest.datasette.io/fixtures/facetable
|
|
|
|
Options:
|
|
--token TEXT API token
|
|
-v, --verbose Verbose output
|
|
--help Show this message and exit.
|
|
|
|
```
|
|
<!-- [[[end]]] -->
|
|
|
|
## dclient rows --help
|
|
<!-- [[[cog
|
|
import cog
|
|
from dclient import cli
|
|
from click.testing import CliRunner
|
|
runner = CliRunner()
|
|
result = runner.invoke(cli.cli, ["rows", "--help"])
|
|
help = result.output.replace("Usage: cli", "Usage: dclient")
|
|
cog.out(
|
|
"```\n{}\n```".format(help)
|
|
)
|
|
]]] -->
|
|
```
|
|
Usage: dclient rows [OPTIONS] [URL_OR_ALIAS]
|
|
|
|
Browse rows in a Datasette table with filtering and sorting
|
|
|
|
Example usage:
|
|
|
|
dclient rows https://latest.datasette.io/fixtures/facetable
|
|
dclient rows https://latest.datasette.io/fixtures/facetable -w state=CA
|
|
dclient rows https://latest.datasette.io/fixtures/facetable --sort city
|
|
dclient rows https://latest.datasette.io/fixtures/facetable --search text
|
|
|
|
Options:
|
|
--token TEXT API token
|
|
-w, --where TEXT Filter: column__op=value (e.g. age__gt=30)
|
|
--where-sql TEXT Raw SQL WHERE clause
|
|
--search TEXT Full-text search query
|
|
--sort TEXT Sort by column (ascending)
|
|
--sort-desc TEXT Sort by column (descending)
|
|
--col TEXT Include only these columns
|
|
--nocol TEXT Exclude these columns
|
|
--facet TEXT Facet by column
|
|
--size INTEGER Number of rows per page
|
|
--all Fetch all pages
|
|
--limit INTEGER Maximum total rows to return
|
|
-v, --verbose Verbose output
|
|
--csv Output as CSV
|
|
--tsv Output as TSV
|
|
--json Output as JSON (default)
|
|
--nl Output as newline-delimited JSON
|
|
--table Output as text table
|
|
--help Show this message and exit.
|
|
|
|
```
|
|
<!-- [[[end]]] -->
|
|
|
|
## dclient get --help
|
|
<!-- [[[cog
|
|
import cog
|
|
from dclient import cli
|
|
from click.testing import CliRunner
|
|
runner = CliRunner()
|
|
result = runner.invoke(cli.cli, ["get", "--help"])
|
|
help = result.output.replace("Usage: cli", "Usage: dclient")
|
|
cog.out(
|
|
"```\n{}\n```".format(help)
|
|
)
|
|
]]] -->
|
|
```
|
|
Usage: dclient get [OPTIONS] [URL_OR_ALIAS] PK_VALUES
|
|
|
|
Fetch a single row by primary key
|
|
|
|
Example usage:
|
|
|
|
dclient get https://latest.datasette.io/fixtures/facetable 1
|
|
dclient get https://latest.datasette.io/fixtures/compound_pk a,b
|
|
|
|
Options:
|
|
--token TEXT API token
|
|
-v, --verbose Verbose output
|
|
--help Show this message and exit.
|
|
|
|
```
|
|
<!-- [[[end]]] -->
|