Query a branch

Infrahub holds proposed changes in branches. With branch=<name>, a consumer reads an inventory as it would be if the branch were merged: contributions whose source has the branch supply their branch data, and the others supply their default data. The response states which data each contribution supplied and why.

curl -s 'localhost:8080/v1/inventories/devices/entities?branch=change-42'

branch works on entity lists, lookups and diagnostics. Census passes the branch name unchanged to each source.

What each contribution supplies

"view": {
  "branch": "change-42",
  "contributions": [
    { "id": "infrahub", "view": "branch", "reason": null },
    { "id": "netbox", "view": "default", "reason": "source does not branch" }
  ]
}

Source	view	reason
Has the branch	branch	null
Supports branches, but does not have this branch	default	branch not found in source
Does not support branches (NetBox)	default	source does not branch

Without branch, view.branch is null and view.contributions is empty.

A branch view follows the same HFID, resolution, normalization and filter rules as the default view. If a branch renames an object in one source while another source keeps the old name, the branch view holds two entities.

When a branch query fails

Case	Response
No source of the inventory has the branch	404 branch-not-found
A source that supports branches cannot be reached, and Census does not hold the view yet	503 branch-unavailable, with the contribution and the error
branch= with an empty value	400 invalid-query

Census does not use default data in place of branch data it could not read.

How long a branch view lasts

Census builds a branch view the first time a query names the branch, by refreshing every contribution of the inventory on that branch. The first query therefore takes longer than the next ones. After that:

• Census refreshes the views it holds on the shortest refresh_interval among all contributions, and applies Infrahub webhooks for the branch.
• Census holds at most [branching].max_views views, three by default, counted across all inventories. A view is one inventory on one branch. A query for one more view retires the view read least recently.
• Census retires a view that no query has read for [branching].idle_ttl, one hour by default.
• If a refresh of a held view fails, Census keeps the view's data and reports the contribution as degraded.
• When every source that supplied the branch no longer has it, Census retires the view. The next query for the branch builds it again, or returns 404 branch-not-found.

Completeness and contribution health in a branch response describe the branch view.