Wiki source code of 15 Annex 5 - Query Samples
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
1.1 | 1 | {{box title="**Contents**"}} |
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | == 15.1 Scope == | ||
| 6 | |||
| |
2.1 | 7 | This annex includes a set of example queries which walk through the process of querying a [[data source>>doc:sdmx:Glossary.Data source.WebHome]] for the purposes of data discovery. It also includes an additional section which details some of the advanced features of the [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] query message. |
| |
1.1 | 8 | |
| 9 | == 15.2 Discovering Categories == | ||
| 10 | |||
| |
2.1 | 11 | The first step a user may take in discovering data is to see the [[categories>>doc:sdmx:Glossary.Category.WebHome]] 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>>doc:sdmx:Glossary.Category.WebHome]] for such data. |
| |
1.1 | 12 | |
| 13 | === 15.2.1 REST === | ||
| 14 | |||
| |
2.1 | 15 | 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>>doc:sdmx:Glossary.Category.WebHome]] is to retrieve all [[categories>>doc:sdmx:Glossary.Category.WebHome]] and filter through the results. Such a query would be structured as follows: |
| |
1.1 | 16 | |
| 17 | http:~/~/ws-entry-point/categoryscheme | ||
| 18 | |||
| 19 | A sample result for this can be seen in the sample file, ecb_query/ecb_exr_category_rest.xml. | ||
| 20 | |||
| |
2.1 | 21 | Note that the entire [[category scheme>>doc:sdmx:Glossary.Category scheme.WebHome]] is returned. If the [[data source>>doc:sdmx:Glossary.Data source.WebHome]] had more [[category schemes>>doc:sdmx:Glossary.Category scheme.WebHome]], these would have been returned as well. |
| |
1.1 | 22 | |
| 23 | === 15.2.2 SOAP === | ||
| 24 | |||
| |
3.1 | 25 | Using the SOAP query, one can query for a [[category>>doc:sdmx:Glossary.Category.WebHome]] 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>>doc:sdmx:Glossary.Category scheme.WebHome]] where a [[category>>doc:sdmx:Glossary.Category.WebHome]] 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>>doc:sdmx:Glossary.Category.WebHome]] are returned. |
| |
1.1 | 26 | |
| 27 | == 15.3 Discovering Data Structures == | ||
| 28 | |||
| |
3.1 | 29 | After the user queried for [[categories>>doc:sdmx:Glossary.Category.WebHome]], he can now examine these [[categories>>doc:sdmx:Glossary.Category.WebHome]] 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>>doc:sdmx:Glossary.Category.WebHome]] (2018773.2018810.2018779.2018795). The user will want to find [[data flows>>doc:sdmx:Glossary.Dataflow.WebHome]] which are categorised against this [[category>>doc:sdmx:Glossary.Category.WebHome]]. |
| |
1.1 | 30 | |
| 31 | === 15.3.1 REST === | ||
| 32 | |||
| |
3.1 | 33 | In the REST syntax, the user will have to query for the [[category scheme>>doc:sdmx:Glossary.Category scheme.WebHome]] in which the exchange rate is defined and request that categorisations and their references be returned. This query would be as follows: |
| |
1.1 | 34 | |
| 35 | http:~/~/ws-entry-point/categoryscheme/ECB/SDW_ECONOMIC_CONCEPTS/1.0?references="parentan dsiblings" | ||
| 36 | |||
| |
3.1 | 37 | 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>>doc:sdmx:Glossary.Category.WebHome]] of the queried [[category scheme>>doc:sdmx:Glossary.Category scheme.WebHome]] 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>>doc:sdmx:Glossary.Dataflow.WebHome]] categorised against the one [[category>>doc:sdmx:Glossary.Category.WebHome]]. In reality, all categorisations and their objects for the entire [[category scheme>>doc:sdmx:Glossary.Category scheme.WebHome]] would be returned. |
| |
1.1 | 38 | |
| 39 | === 15.3.2 SOAP === | ||
| 40 | |||
| |
3.1 | 41 | 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>>doc:sdmx:Glossary.Category.WebHome]], and only categorisation which categorise [[data flows>>doc:sdmx:Glossary.Dataflow.WebHome]]. Further, it can omit the actual categorisation from the results, leaving only the [[dataflow>>doc:sdmx:Glossary.Dataflow.WebHome]] 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. |
| |
1.1 | 42 | |
| 43 | == 15.4 Discovering Data == | ||
| 44 | |||
| |
3.1 | 45 | Now that the [[dataflow>>doc:sdmx:Glossary.Dataflow.WebHome]] has been found for the effective exchange rate data, the actual data reported against this flow can be retrieved. |
| |
1.1 | 46 | |
| 47 | === 15.4.1 REST === | ||
| 48 | |||
| |
3.1 | 49 | In the REST syntax, the data query is very straight forward for querying for an entire [[data set>>doc:sdmx:Glossary.Data set.WebHome]] for a give [[data flow>>doc:sdmx:Glossary.Dataflow.WebHome]], in this case the effective exchange rates flow (2034482): |
| |
1.1 | 50 | |
| 51 | http:~/~/ws-entry-point/data/2034482 | ||
| 52 | |||
| 53 | 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. | ||
| 54 | |||
| 55 | === 15.4.2 SOAP === | ||
| 56 | |||
| |
3.1 | 57 | 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>>doc:sdmx:Glossary.Dimension.WebHome]] to orient the data on. The implication is that the [[data source>>doc:sdmx:Glossary.Data source.WebHome]] will return the data oriented with the [[dimension>>doc:sdmx:Glossary.Dimension.WebHome]] it chooses at the observation (% style="color:#e74c3c" %)level(%%). In this case, it is the time [[dimension>>doc:sdmx:Glossary.Dimension.WebHome]]. |
| |
1.1 | 58 | |
| 59 | The result for this query is the same as the REST and is shown in the sample file ecb_query\ecb_exr_data.xml. | ||
| 60 | |||
| |
3.1 | 61 | Technically, the query for the [[dataflow>>doc:sdmx:Glossary.Dataflow.WebHome]] was not actually necessary to discover the data using the SOAP query. It is possible to query for data directly by a [[category>>doc:sdmx:Glossary.Category.WebHome]] - with the result being any data in which the [[data set>>doc:sdmx:Glossary.Data set.WebHome]], the data structure, the [[data flow>>doc:sdmx:Glossary.Dataflow.WebHome]], or the [[provision agreement>>doc:sdmx:Glossary.Provision agreement.WebHome]] which is categorised against the referenced [[category>>doc:sdmx:Glossary.Category.WebHome]]. |
| |
1.1 | 62 | |
| 63 | == 15.5 Better Data Queries == | ||
| 64 | |||
| |
3.1 | 65 | 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>>doc:sdmx:Glossary.Dataflow.WebHome]] 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>>doc:sdmx:Glossary.Code.WebHome]] to do things such as search for exchange rates for only select [[currencies>>doc:sdmx:Glossary.Currency.WebHome]]. |
| |
1.1 | 66 | |
| 67 | === 15.5.1 REST === | ||
| 68 | |||
| |
3.1 | 69 | To retrieve the full details of the data structure in REST based on the [[dataflow>>doc:sdmx:Glossary.Dataflow.WebHome]], one simply queries for the [[data flow>>doc:sdmx:Glossary.Dataflow.WebHome]] and all descendant references: |
| |
1.1 | 70 | |
| 71 | http:~/~/ws-entry-point/dataflow/ECB/2034482/1.0?references="descendants" | ||
| 72 | |||
| 73 | The sample file ecb_query/ecb_exr_structure.xml shows the result of this query. | ||
| 74 | |||
| 75 | === 15.5.2 SOAP === | ||
| 76 | |||
| 77 | 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. | ||
| 78 | |||
| 79 | == 15.6 Other Structural Metadata Query Features == | ||
| 80 | |||
| |
3.1 | 81 | There is a sample set included with this document that serve to highlight some of the more advanced mechanisms in the [[structural metadata>>doc:sdmx:Glossary.Structural metadata.WebHome]] queries. These sample files are as follows. |
| |
1.1 | 82 | |
| 83 | Directory Name: query | ||
| 84 | |||
| 85 | Description: query messages and corresponding result files Contents: | ||
| 86 | |||
| 87 | (% style="width:949.446px" %) | ||
| 88 | |**Name**|(% style="width:686px" %)**Description** | ||
| 89 | |query_cl_all.xml|(% style="width:686px" %)a query for a subset of the very large area code list; return details specify that the matched item should be cascaded down the hierarchy, meaning all of its child codes should be returned; results in all regions and sub-regions for Greece | ||
| 90 | |repsonse_cl_all.xml|(% style="width:686px" %)response for query_cl_all.xml | ||
| 91 | |query_cl_regions.xml|(% style="width:686px" %)query for only the regions that are direct children of Greece; uses the parent property of the code to find the administrative regions within the country; results are not cascaded, so only one level is returned | ||
| 92 | |response_cl_regions.xml|(% style="width:686px" %)response for query_cl_regions.xml | ||
| 93 | |query_demo_stub.xml|(% style="width:686px" %)query which demonstrates how one can check for the existence of an object by simply requesting that no references be resolved and only the stub be returned; intention of this query is to simply find out what is the version of the currently active demography data structure | ||
| 94 | |response_demo_stub.xml|(% style="width:686px" %)response for query_demo_stub.xml | ||
| 95 | |query_esms_children.xml|(% style="width:686px" %)query which demonstrates reference resolution and mixing return details; only objects directly referenced from the queries metadata structure are returned; the full details of the metadata structure are returned and only the stubs of the queried objects are returned | ||
| 96 | |response_esms_children.xml|(% style="width:686px" %)response for query_esms_children.xml | ||
| 97 | |query_esms_descendants.xml|(% style="width:686px" %)where used query; intention is to query for any objects which are used directly or indirectly by the ESMS metadata structure; metadata structure is requested to not be returned; only the stubs of all objects referenced form the metadata structure and the object which they reference (and so on) are returned | ||
| 98 | |response_esms_descendants.xml|(% style="width:686px" %)response for query_esms_descendants.xml |