15 Annex 5 - Query Samples

15.1 Scope

This annex includes a set of example queries which walk through the process of querying a data source for the purposes of data discovery. It also includes an additional section which details some of the advanced features of the SDMX query message.

15.2 Discovering Categories

The first step a user may take in discovering data is to see the categories which data might be classified against. In this example scenario, a user is trying to find exchange rate data from the European Central Bank. The first step is to discover if there is a category for such data.

15.2.1 REST

In the REST syntax, there is no means to search based on text, so the simplest means for the user to find the exchange rate category is to retrieve all categories and filter through the results. Such a query would be structured as follows:

http://ws-entry-point/categoryscheme

A sample result for this can be seen in the sample file, ecb_query/ecb_exr_category_rest.xml.

Note that the entire category scheme is returned. If the data source had more category schemes, these would have been returned as well.

15.2.2 SOAP

Using the SOAP query, one can query for a category by name, and request that only the matched items be returned. The sample file, ecb_query/ecb_exr_category_soap.xml demonstrates a query for category schemes where a category contains the text "Exchange rate" in its English name. Note that it also request that only matched items and their children be returned. The result file for this query is ecb_query/ecb_exr_category_soap.xml. It can be seen from this result file that only the relevant categories are returned.

15.3 Discovering Data Structures

After the user queried for categories, he can now examine these categories in order to determine how to proceed with the data discovery process. Suppose that upon examination the user decide that he actually wanted data for the effective exchange rate category (2018773.2018810.2018779.2018795). The user will want to find data flows which are categorised against this category.

15.3.1 REST

In the REST syntax, the user will have to query for the category scheme in which the exchange rate is defined and request that categorisations and their references be returned. This query would be as follows:

http://ws-entry-point/categoryscheme/ECB/SDW_ECONOMIC_CONCEPTS/1.0?references="parentan dsiblings"

Note the references parameter. It specifies parent (i.e. objects referencing the queried object) and siblings, objects referenced directly from the parent object. This will return categorisations which reference the categories of the queried category scheme and the objects which these categorisations categorise. The sample file, ecb_query/ecb_exr_dataflow_rest.xml shows the result of this query. Note that this assumes that there is only one data flow categorised against the one category. In reality, all categorisations and their objects for the entire category scheme would be returned.

15.3.2 SOAP

The SOAP syntax is able to take a much more direct approach. It can query directly for categorisations which use the specific effective exchange rate category, and only categorisation which categorise data flows. Further, it can omit the actual categorisation from the results, leaving only the dataflow to be returned. The sample file, ecb_query\ecb_exr_dataflow_query.xml shows this sample query and ecb_query\ecb_exr_dataflow_soap.xml shows the result.

15.4 Discovering Data

Now that the dataflow has been found for the effective exchange rate data, the actual data reported against this flow can be retrieved.

15.4.1 REST

In the REST syntax, the data query is very straight forward for querying for an entire data set for a give data flow, in this case the effective exchange rates flow (2034482):

http://ws-entry-point/data/2034482

The result for this query is shown in the sample file ecb_query\ecb_exr_data.xml. Note that this result assumes that the REST request specified that it wished to receive structured specific data.

15.4.2 SOAP

The query in the SOAP syntax is just as simple, as shown in ecb_query/ecb_exr_data_query.xml. The request is for structure specific data, but does not specify which dimension to orient the data on. The implication is that the data source will return the data oriented with the dimension it chooses at the observation level. In this case, it is the time dimension.

The result for this query is the same as the REST and is shown in the sample file ecb_query\ecb_exr_data.xml.

Technically, the query for the dataflow was not actually necessary to discover the data using the SOAP query. It is possible to query for data directly by a category - with the result being any data in which the data set, the data structure, the data flow, or the provision agreement which is categorised against the referenced category.

15.5 Better Data Queries

The above example assumes a very simple scenario, where the data itself was not actually queried. In actuality, such a query may not be wise as the volume of data returned could be quite large. In a more realistic scenario, one might choose to first examine the data structure for the data flow in order to determine what data might be available. After the full data structure details are returned, one can examine the dimensionality of the data and even look at the available codes to do things such as search for exchange rates for only select currencies.

15.5.1 REST

To retrieve the full details of the data structure in REST based on the dataflow, one simply queries for the data flow and all descendant references:

http://ws-entry-point/dataflow/ECB/2034482/1.0?references="descendants"

The sample file ecb_query/ecb_exr_structure.xml shows the result of this query.

15.5.2 SOAP

The SOAP query is similarly simple, as show in the sample file ecb_query/ecb_exr_data_structure_query.xml. The sample file ecb_query/ecb_exr_structure.xml also shows the result of this query.

15.6 Other Structural Metadata Query Features

There is a sample set included with this document that serve to highlight some of the more advanced mechanisms in the structural metadata queries. These sample files are as follows.

Directory Name: query

Description: query messages and corresponding result files Contents: