mirror of
https://github.com/simonw/dclient.git
synced 2026-11-09 19:58:34 +01:00
Update documentation for new commands and output formats
- 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
This commit is contained in:
Claude
parent
364c344d8d
commit
02dd3ae9ca
7 changed files with 709 additions and 25 deletions
347
docs/exploring.md
Normal file
347
docs/exploring.md
Normal file
|
|
@ -0,0 +1,347 @@
|
|||
# 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]]] -->
|
||||
Loading…
Add table
Add a link
Reference in a new issue