dclient/docs/exploring.md

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:

dclient databases https://latest.datasette.io

Use --table for a formatted text table:

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:

dclient tables https://latest.datasette.io/fixtures

Use --table for formatted output:

dclient tables https://latest.datasette.io/fixtures --table

Use --schema to include the CREATE TABLE SQL for each table:

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:

# 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:

dclient rows https://latest.datasette.io/fixtures/facetable --table

Filtering

Use -w / --where to filter rows. Supports Datasette filter operators like __gt, __contains, __exact, etc.:

# 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:

dclient rows https://example.com/db/dogs --where-sql "age > 3 and breed != 'Poodle'"

Sorting

# 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

# 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

dclient rows https://example.com/db/articles --search "python tutorial"

Faceting

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:

dclient rows https://example.com/db/dogs --all

Control page size with --size and limit total rows with --limit:

# 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:

dclient get https://latest.datasette.io/fixtures/facetable 1

Output:

{
  "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:

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

dclient rows https://example.com/db/dogs --csv > dogs.csv
dclient rows https://example.com/db/dogs --table

dclient databases --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.

dclient tables --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.

dclient schema --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.

dclient rows --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.

dclient get --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.