The entity map on your machine

The entity map is built on every audit and every squirrel analyze, stored in the project database, and carried on the report. Nothing extra to enable, and it never touches the health score: it is a description of what a site declares, not a verdict on it.

Three ways to reach it locally: read it in a report, query it with squirrel entities, or read the store directly.

In a report

Every format carries the map, and each one carries as much of it as that format is good at.

squirrel audit https://example.com
squirrel report -f html -o report.html    # the graph
squirrel report -f json | jq .entities    # the document

squirrel entities

Queries a stored map without re-auditing.

squirrel entities                                  # summary of the latest audit
squirrel entities --list                           # stored audits and their entity counts
squirrel entities "https://example.com/#org"       # one entity, by @id
squirrel entities "Acme"                           # or by name
squirrel entities --problem no-id                  # what needs fixing
squirrel entities -f jsonld -o graph.json          # export
squirrel entities --diff                           # what changed since last time

Full reference, with worked output for each: squirrel entities.

Flags

Problems

--problem takes any of five, and repeating the flag is an OR:

Different filters combine as an AND. --type Organization --problem no-id keeps organizations that also have that problem.

Formats

--diff accepts markdown (default) or json only.

Every filter applies to every format, so -f dot --type Organization exports the organizations subgraph rather than the whole thing filtered afterwards.

Comparing two audits

squirrel entities --diff                                   # previous vs latest, same site
squirrel entities --diff --crawl 9c1de77a                  # that audit vs its predecessor
squirrel entities --diff --crawl 4f2ab91c --crawl 9c1de77a # both sides named
squirrel entities --diff --input before.json --input after.json
squirrel entities --diff -f json                           # for a CI job

With no arguments it compares the latest against the previous audit of the same site, because the store holds every project and the two newest audits are routinely two different sites.

The output separates what changed from what was not looked at. An entity absent from the newer audit is only removed when every page that declared it was crawled again; anything else is not crawled again. A smaller crawl therefore never reads as a site that deleted its structured data.

An entity that gained or lost an @id is matched across the key change and reported once, with a coverage column saying whether the newer audit both revisited the pages that were wrong and found the replacement there. The format page explains why both halves are required.

In the store

The map lives in the project database, ~/.squirrel/projects/<project>/project.db on macOS and Linux, in three tables. You can query them directly; nothing here is private.

entity_occurrences is the one worth knowing about. A node’s pages array is capped at 50, so it cannot answer “every page that declares this Organization”. This table can, and so can the document’s own top-level pages[].declares index, which is not capped. What you cannot use is the node’s page array.

-- every page declaring one entity, uncapped
SELECT normalized_url FROM entity_occurrences
WHERE crawl_id = ? AND key = 'id:https://example.com/#organization';

-- entities declared on several pages with no @id, widest first
SELECT key, name, page_count FROM entities
WHERE crawl_id = ? AND entity_id IS NULL AND page_count > 1
ORDER BY page_count DESC;

References

• squirrel entities — the command reference with worked output
• The entity map — what it is and how to read it
• The entity map format — the documents this produces
• The entity map in the cloud — the same map, hosted
• The entity map for agents — the MCP tools over the same data
• Fixing structured data identity — the change to make in each generator