dqt — DEPAROM Query Translator

The service is primarily tailored for our DEPAROM Profil customers and anyone else who wants to use queries in the DEPAROM query language to search the DEPAROM index. It provides a RESTful interface to receive DEPAROM queries and returns a matching Elasticsearch query to be used on the DEPAROM index.

Information Required

In order to use the DEPAROM Query Translator you will need a DEPAROM Query to translate. You can get one from your latest DEPAROM volume. Alternatively you can write your own based on the below examples and the documentation of the DEPAROM Recherche Client which is available for download.

Tutorial

In order to send data to the HTTP API you need some form of REST client. This can be a basic tool like cURL, a fully featured REST client like Insomnia or any client library targeted for your development language. For this tutorial we will assume cURL and provide examples as cURL commands, since it is a widely available tool on most operating systems. We want to send a DEPAROM query to the service, so that we can get a translated query back which we can then use, to query the Elasticsearch index. We also need to authenticate against the proxy with our credential using http simple authentication. A cURL command would look like the following:

cURL Command Example

1$ curl -u username:password -XPOST 'https://api.depa.tech/dqt/query/es' -H 'Content-Type: application/json' -d ' 
2  DEPAROM V1.0 
3  1
4  ( 
5    ( 
6      IC=B62B0001
7      OR IC=B62B0003 
8    )
9    AND 
10    ( 
11      KI=A* or KI=B* or KI=U*
12    ) 
13  OR
14    PA*=WANZL,CADDIE,MARSANZ
15  )
16  AND
17  ( 
18    PC*=DE,EP,US,WO
19  )'

This will result in a response which carries the query object in JSON format, ready to be inserted in an Elasticsearch query. The returned output should look like this:

response example

1{
2    "bool": {
3     "must": [
4      {
5       "bool": {
6        "should": [
7         {
8          "bool": {
9           "must": [
10            {
11             "bool": {
12              "should": [
13               {
14                "term": {
15                 "IC": "B62B0001"
16                }
17               },
18               {
19                "term": {
20                 "IC": "B62B0003"
21                }
22               }
23              ]
24             }
25            },
26            {
27             "bool": {
28              "should": [
29               {
30                "regexp": {
31                 "KI": "A.*"
32                }
33               },
34               {
35                "regexp": {
36                 "KI": "B.*"
37                }
38               },
39               {
40                "regexp": {
41                 "KI": "U.*"
42                }
43               }
44              ]
45             }
46            }
47           ]
48          }
49         },
50         {
51          "query_string": {
52           "fields": ["PA"],
53           "query": "WANZL",
54           "default_operator": "AND"
55          }
56         },
57         {
58          "query_string": {
59           "fields": ["PA"],
60           "query": "CADDIE",
61           "default_operator": "AND"
62          }
63         },
64         {
65          "query_string": {
66           "fields": ["PA"],
67           "query": "MARSANZ",
68           "default_operator": "AND"
69          }
70         }
71        ]
72       }
73      },
74      {
75       "bool": {
76        "should": [
77         {
78          "term": {
79           "PC": "DE"
80          }
81         },
82         {
83          "term": {
84           "PC": "EP"
85          }
86         },
87         {
88          "term": {
89           "PC": "US"
90          }
91         },
92         {
93          "term": {
94           "PC": "WO"
95          }
96         }
97        ]
98       }
99      }
100     ]
101    }
102   }

If you are familiar with Elasticsearch queries you will notice, that the payload does not resemble a proper Elasticsearch query. This is on purpose. The returned JSON object is to be used as an inner query object either by embedding it in the root query object or as part of a larger query like a bool query. The most simple approach would look like this:

embedded JSON object example

1{"query":{"bool":{"must":[{"bool":{"must":[{"bool":{"should":[{"regexp":{"IC":"B62B0001"}},
2{"regexp":{"IC":"B62B0003"}}]}},{"bool":{"should":[{"bool":{"should":[{"regexp":{"KI":"A.*"}},
3{"bool":{"should":[{"regexp":{"KI":"B.*"}},{"regexp":{"KI":"U.*"}}]}}]}},{"bool":{"should":
4[{"terms":{"PA":["WANZL","CADDIE","MARSANZ"]}}]}}]}}]}},{"bool":{"should":[{"terms":
5{"PC":["DE","EP","US","WO"]}}]}}]}}}

As you see, the result JSON is set as the “query” key in the Elasticsearch root query object. For more details on how to query the DEPAROM index, please refer to the Elasticsearch index section of this documentation.

Known Issues

Quotation marks around values

At the moment you are encouraged to put any text value which has a length of 2 characters or less in quotation marks like so: PC=“DE”. Currently there is a problem with the parser which confuses values which are equal to field names for field names, resulting in an error.

Truncations with asterisk

Truncation currently only work in the KI field, due to a bug in the translator.

API Documentation

Translate Query

BASE URL	https://api.depa.tech
Endpoint	/dqt/query/es
Method	POST
Notes	Send a query in DEPAROM format in the request body and get a query Elasticsearch format returned.

Usage Example:

translate query example

1$ curl -u username:password -XPOST 'https://api.depa.tech/dqt/query/es' -H 'Content-Type: application/json' -d '
2  DEPAROM V1.0
3  1
4  PC=DE
5  '

Back to Manuals