Glossary

Domain and technical terms you meet when using ddb. For the option reference see the README and the full cookbook in Usage.md.

ddb targets the DDB v2 API (https://api.deutsche-digitale-bibliothek.de/2). Its read routes — search, item, version — are public: no API key.

The DDB and its data

Deutsche Digitale Bibliothek (DDB). Germany’s national aggregator for digitised cultural and scientific heritage. It does not hold objects itself; it harvests metadata from ~500 partner institutions (archives, libraries, museums, research bodies) and offers one shared search across them.

Object / item. A single catalogued thing — a book, image, archival record, piece of sheet music, film, audio recording, etc. Identified by a 32-character id (e.g. TNPFDKO2VDGBZ72RWC6RKDNZYZQZP3XK), the value in a search result’s id and the argument to ddb item.

Institution / provider. A data partner that contributes objects. There is no dedicated institutions command in this CLI; filter or aggregate by provider through the provider_fct facet instead (--facet provider_fct, or --filter provider_fct:"…").

Sector (Sparte). The cultural sector an object’s provider belongs to, exposed as the sector_fct facet with codes sec_01..sec_07: Archive, Library, Monument protection, Research, Media, Museum, Other.

Search

v2 = Solr passthrough. In v2, ddb search is a thin wrapper over the DDB’s Apache Solr index (GET /2/search/index/{collection}/{requestHandler}, by default search/select). Your options map onto native Solr query parameters and the response is native Solr JSON, not a DDB-curated envelope.

Solr / Lucene query syntax. search queries use bare keywords, "quoted phrases", boolean AND/OR/NOT, field-scoped terms (title:Faust), ranges, and *:* to match every document.

q (the query). The search term(s). Required; pass '*:*' to browse all objects. ddb search caps results at --rows 10 by default.

rows / start. --rows is the page size (Solr rows); --offset is how many leading documents to skip (Solr start). Together they page a result set.

Response shape. A Solr response has four parts you care about:

Document fields. Each docs[] entry carries the item id plus many Solr fields — commonly label / title (display text), type (media-type codes), objecttype, place / place_fct, provider / provider_fct, preview (thumbnail URL), license. Fields vary by object; project what you need with jq.

Facet. A field the index can group and count by — object type, place, provider, language, sector, time. --facet <field> asks Solr to return value counts for that field, in facet_counts.facet_fields.<field> as a flat array [value, count, value, count, …]. The array can include values with count 0, and values are delivered as the institutions wrote them (place_fct has München next to München, Oktoberfest).

*_fct fields. The DDB’s facet field names end in _fct. The common ones:

There is no time_fct and no federal-state facet: time_fct and state_fct are undefined fields, and using one fails with HTTP 500 (exit 1).

The type_fct codes, as labelled by the objects’ item.media value (sampled 2026-09-15): mediatype_001 audio, mediatype_002 image, mediatype_003 text, mediatype_005 video, mediatype_007 unknown (no digitised media, metadata only), mediatype_010 3D.

--facet vs. --filter. --facet type_fct asks Solr to return counts for that field (so you can see what to narrow to). --filter takes a raw Solr filter query (fq) that restricts the result set, e.g. --filter place_fct:"Berlin" or --filter type_fct:mediatype_002. Repeat --filter to AND several constraints; express OR inside one fq (--filter 'place_fct:("Berlin" OR "Dessau")').

sort. Solr sort syntax: <field> asc|desc, e.g. --sort "score desc" (relevance, the default when omitted) or --sort "id asc". Comma-separate for tie-breakers (--sort "score desc, id asc").

fields (fl). --fields id,label,type restricts each returned document to those fields (Solr fl) — the cleanest way to tame verbose docs.

Item components

Item components. ddb item <id> --part <component> fetches one component of an object. Most are JSON; a few are served as XML or a plain file and are printed raw (so > file.xml and piping keep them intact):

--part children also accepts --rows / --offset for paging a large child set. --lang <code> sets the preferred label language for view/aip/edm/binaries/source/source-description; an object without a record in that language answers 404 (seen for --lang en).

Auth & rights

No API key. The read routes this CLI uses are public — search, item and version all work anonymously. A 403 is therefore unusual and means --base-url was pointed at an authenticated endpoint, or the specific item component is access-restricted — not “you need a key”.

CC0 1.0. The Creative Commons “no rights reserved” public-domain dedication. The DDB API returns metadata exclusively under CC0 — freely reusable, no attribution required.

Rights statement / Lizenzkorb. The DDB’s “license basket”: the fixed set of rights notices an institution may attach to a digital object’s media (image, audio, video) — CC0, CC BY, CC BY-SA, Public Domain Mark, various In Copyright / Rights Reserved statements. Object media (not downloaded by this CLI) can therefore be more restricted than the CC0 metadata — always check the individual object’s rights before reusing its media: in view the media licence URI is item.license.resource (item.rights is often empty), in binaries it is each file’s kind. See DATA_LICENSE.md.

CLI / technical

Exit codes. 0 success · 2 usage error (bad flag, wrong-length id) · 4 not found · 6 network failure · 1 other API/runtime error. See Usage.md.

Cross-origin credential stripping. The read routes send no credentials, but if you inject one via a header and the API ever redirects to a different host, the client removes any Authorization / Cookie / X-API-Key header before following, so it is never leaked to another origin.