Work with results

By default, every extraction is saved locally under a handle like 20260719-k7m2p9. A handle identifies one result as the page looked when you fetched it. Use latest anywhere a command expects a handle to work with the newest one.

Start with the page map

analog open latest

Reopening a result does not fetch or extract the page again. The preview keeps the page in reading order: each record section shows its label, record count, fields, and a sample; prose and navigation remain in their original positions. Coverage notes say when the saved result contains only part of what the page offered.

To read the whole page as Markdown instead:

analog open latest --markdown

In Python, result.preview() provides the same orientation view.

Inspect and find

Use the preview’s real field names in the commands that follow:

analog describe latest
analog find latest "Einstein"
analog distinct latest tags

describe reports each section’s fields, coverage, distinct-value counts, and samples. find searches records, prose, and page regions in reading order; navigation links are records too, so they are searchable. distinct counts the values in one field. Add --field to find when you want to search only one field.

Export the records you need

Choose a record section from the preview and export it:

analog export <handle> -f csv --section <section>

--section accepts the displayed section number or label. Omit it when the result contains one dataset, or several sections that can be safely combined. Choose json, csv, yaml, or md. You can also select fields, filter rows, sort, and limit the output:

analog export <handle> -f csv --fields name,price \
  --where "price < 20" --sort price --limit 10

Numeric filters and sorting use the underlying number while exports keep the page’s display value, such as "from $5.41". Use --section, --kind, or --collection when you want records from one part of a page rather than every compatible record.

Compare two saves

Fetch the page again when you want a new snapshot, then compare it with the earlier result:

analog get <url>
analog diff <older-handle> latest

diff compares corresponding sections and reports record turnover, fields or sections that appeared or disappeared, count changes, and changes in field coverage. The comparison itself is local and does not fetch either result again. Use --section or --kind to narrow it.

Choose the right Python view

The object returned by analog() and one reopened with results.open(handle) offer the same views:

from analog import analog

result = analog("https://quotes.toscrape.com/js/")
print(result.records[:3])

result.records is the simplest view when the page contains one dataset, or several sections Analog can safely combine. If the page contains different kinds of records, it raises an error rather than flattening them into one misleading list.

Use the view that matches the question:

• result.structured_content contains the physical record sections in page order. Select one by heading with result.section(label), or every section of a kind with result.sections_by_kind(kind).
• result.sections keeps record sections and prose together in the page’s reading order. Use it when placement or surrounding text matters.
• result.collections combines compatible sections when the same entities appear in several places. A collection provides one record per identity while retaining the source sections and placements.
• result.outline shows the page regions Analog found and whether each became records, remained page context, or was not extracted. Use it to distinguish content that was absent from content that was present but not returned as records.

Python exports include to_json(), to_yaml(), to_csv(), and the optional pandas-backed to_dataframe(). Exact attributes, parameters, and return types are in the Python API reference.

Manage saved results

analog history
analog rename <handle> quarterly-prices
analog rm --older-than 30d --dry-run

history lists saved results newest first with their handles, source URLs, ages, and record counts. A friendly name works anywhere a handle does. Use --dry-run before deleting a group of results by age or URL.

Saved artifacts contain the structured records, ordered Markdown regions, and page Markdown, never raw HTML. analog history --usage shows their disk footprint. The store is size-bounded and evicts the least recently opened results first; ANALOG_CACHE_DIR overrides the system cache location.

Exit codes

All commands use the same categories so scripts can branch on $?: 0 success, 1 command error, 2 usage, 3 auth, 4 backend unreachable, 5 fetch refused/failed (including robots.txt refusals), 6 extraction failed.