Unit 4: Reading Referential Metadata
One of the core features of the library is to allow retrieving metadata that can be used to power statistical processes.
These metadata are typically stored in an SDMX Registry, such as the FMR. However, retrieval is not limited to specific registries; any service compliant with the SDMX-REST 2.0.0 specification, allowing metadata retrieval in SDMX-JSON 2.0.0, can be used.
In this unit, we'll take a closer look at reading referential metadata using pysdmx.
SDMX-REST services
Pysdmx allows retrieving metadata from an SDMX Registry in either a synchronous (via pysdmx.api.fmr.RegistryClient) or asynchronous fashion (via pysdmx.api.fmr.AsyncRegistryClient). The choice depends on your use case. The asynchronous client is often preferred, as it is non-blocking.
Useful Examples
What does retrieving metadata from an SDMX Registry using pysdmx look like for synchronous or asynchronous use cases?
Select each image to learn more about these queries, as well as additional details relating to retrieving reference metadata.
Synchronous queries
get_report(provider, id, version=’+’)
Get a reference metadata report.
Parameters:
- provider (str) – The organization which provided the report.
- id (str) – The ID of the report to be returned.
- version (str) – The version of the report to be returned. The most recent version will be returned, unless specified otherwise.
Return type: Metadata Report
Returns: The requested metadata report.
Get_reports(artefact_type, agency, id, version='+')
Get the reference metadata reports for the supplied structure.
Parameters:
- artefact_type (str) – The type of structural metadata to which the reference metadata to be returned are attached.
- agency (str) – The agency maintaining the hierarchy for which reports must be returned.
- id (str) – The ID of the structure for which reports must be returned.
- version (str) – The version of the structure for which reports must be returned.
Return type: Sequence[MetadataReport]
Returns: The metadata reports about the supplied structure.
Asynchronous queries
asyncget_report(provider, id, version=’+’)
Get a reference metadata report.
Parameters:
- provider (str) – The organization which provided the report.
- id (str) – The ID of the report to be returned.
- version (str) – The version of the report to be returned. The most recent version will be returned, unless specified otherwise.
Return type: Metadata Report
Returns: The requested metadata report.
Asyncget_reports(artefact_type, agency, id, version='+')
Get the reference metadata reports for the supplied structure.
Parameters:
- artefact_type (str) – The type of structural metadata to which the reference metadata to be returned are attached.
- agency (str) – The agency maintaining the hierarchy for which reports must be returned.
- id (str) – The ID of the structure for which reports must be returned.
- version (str) – The version of the structure for which reports must be returned.
Return type: Sequence[MetadataReport]
Returns: The metadata reports about the supplied structure.
Retrieving reference metadata
To connect to your target Registry, instantiate the client by passing the SDMX-REST endpoint. If using the FMR, the endpoint is the URL at which the FMR is available, followed by /sdmx/v2/. For example, the SDMX Global Registry URL is "https://registry.sdmx.org" and the endpoint is therefore "registry.sdmx.org/sdmx/v2/".
from pysdmx.api.fmr import AsyncRegistryClient
client = AsyncRegistryClient("[endpoint_comes_here]")
We aim to retrieve configuration details for the BIS_MACRO dataflow. The metadata report for the DCO_BIS_MACRO ID can be obtained using the get_report method:
report = await client.get_report("BIS", "DCO_BIS_MACRO", "1.0")
Iterate over the report to print configuration options:
for attribute in report:
print(attribute)
In practice, instead of printing, these attributes can be used to drive process steps. For example, a validation step can check the value of partial_update to determine whether mandatory attributes need validation.
check_mandatory = report["partial_update"]
What do you know?
Let's try another question. Which one of the following queries is considered synchronous and returns the metadata reports about the supplied structure?
Select your answer and then select Submit.
The query: Get_reports(artefact_type, agency, id, version='+') is synchronous and returns the metadata reports about the supplied structure.
The correct answer is option 2.
The query: Get_reports(artefact_type, agency, id, version='+') is synchronous and returns the metadata reports about the supplied structure.
Coming next
In the next unit, we'll focus on more use case examples to help solidify your understanding of the concepts presented.
Need help finding something? I am an AI Assistant that's here to help!
Welcome to SDMX AI assistant
What are you looking for?
By using this AI-powered service ("Service"), you acknowledge and agree to the following:
This Service uses generative AI to assist with statistical analysis and research. While the Service strives to deliver useful information, the output ("Output") may contain inaccuracies, omissions, or biases. The Output is provided for informational purposes only and should not be considered professional advice. You remain responsible for how you interpret and use the Output.
The BIS makes no warranties regarding the accuracy or completeness of the Output and accepts no liability for any loss or damage resulting from its use.
Do not include or share personal, private, confidential or proprietary information when using the Service.
By using this technology, you agree to the Terms and Conditions.
How the assistant can help you
Understand SDMX standards
Ask and get clear explanations about SDMX standards.
Navigate the website
Find tools and documentation on website quickly.
Explore SDMX tools
Ask about API, software and libraries supporting SDMX.
Access documentation
Locate technical guides, specifications, and FAQs.