You are here:

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 Trans­la­tor you will need a DEPAROM Query to trans­late. You can get one from your lat­est DEPAROM vol­ume. Alter­na­tive­ly you can write your own based on the below exam­ples and the doc­u­men­ta­tion of the DEPAROM Recherche Client which is avail­able for down­load.

Tutorial

n order to send data to the HTTP API you need some form of REST client. This can be a basic tool like cURL, a ful­ly fea­tured REST client like Insom­nia or any client library tar­get­ed for your devel­op­ment lan­guage. For this tuto­r­i­al we will assume cURL and pro­vide exam­ples as cURL com­mands, since it is a wide­ly avail­able tool on most oper­at­ing sys­tems.

We want to send a DEPAROM query to the ser­vice, so that we can get a trans­lat­ed query back which we can then use, to query the Elas­tic­search index.

We also need to authen­ti­cate against the proxy with our cre­den­tial using http sim­ple authen­ti­ca­tion. A cURL com­mand would look like the fol­low­ing:

$ curl -u username:password -XPOST 'https://api.depa.tech/dqt/query/es' -H 'Content-Type: application/json' -d '
DEPAROM V1.0
1
(
    (
        IC=B62B0001
        OR IC=B62B0003
    )
    AND
    (
        KI=A* or KI=B* or KI=U*
    )
OR
    PA*=WANZL,CADDIE,MARSANZ
)
AND
(
    PC*=DE,EP,US,WO
)'

This will result in a response which car­ries the query object in JSON for­mat, ready to be insert­ed in an Elas­tic­search query. The returned out­put should look like this:

{ "bool": { "must": [{ "bool": { "should": [{ "bool": { "must": [{ "bool": { "should": [{ "term": { "IC": "B62B0001" } }, { "term": { "IC": "B62B0003" } }] } }, { "bool": { "should": [{ "regexp": { "KI": "A.*" } }, { "regexp": { "KI": "B.*" } }, { "regexp": { "KI": "U.*" } }] } }] } }, { "query_string": { "fields": ["PA"], "query": "WANZL", "default_operator": "AND" } }, { "query_string": { "fields": ["PA"], "query": "CADDIE", "default_operator": "AND" } }, { "query_string": { "fields": ["PA"], "query": "MARSANZ", "default_operator": "AND" } }] } }, { "bool": { "should": [{ "term": { "PC": "DE" } }, { "term": { "PC": "EP" } }, { "term": { "PC": "US" } }, { "term": { "PC": "WO" } }] } }] } }

If you are famil­iar with Elas­tic­search queries you will notice, that the pay­load does not resem­ble a prop­er Elas­tic­search query. This is on pur­pose. The returned JSON object is to be used as an inner query object either by embed­ding it in the root query object or as part of a larg­er query like a bool query. The most sim­ple approach would look like this:


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

As you see, the result JSON is set as the “query” key in the Elas­tic­search root query object. For more details on how to query the DEPAROM index, please refer to the Elas­tic­search index sec­tion of this doc­u­men­ta­tion.

Known Issues

Quotation marks around values

At the moment you are encour­aged to put any text val­ue which has a length of 2 char­ac­ters or less in quo­ta­tion marks like so: PC=“DE”.
Cur­rent­ly there is a prob­lem with the pars­er which con­fus­es val­ues which are equal to field names for field names, result­ing in an error.

Truncations with asterisk

Trun­ca­tion cur­rent­ly only work in the KI field, due to a bug in the trans­la­tor.

API documentation

Translate query

BASE urlhttps://api.depa.tech
End­point/dqt/query/es
MethodPOST
NotesSend a query in DEPAROM for­mat in the request body and get a query Elas­tic­search for­mat returned.

Usage example:

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