Support "lang" parameter for Koncorde filters

doc/7/controllers/auth/search-api-keys/index.md

@@ -30,6 +30,15 @@ searchApiKeys([query], [options]);
 
 The search query to apply to API keys content, using [ElasticSearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/query-dsl.html) syntax.
 
+<SinceBadge version="auto-version"/>
+
+This method also supports the [Koncorde Filters DSL](/core/2/api/koncorde-filters-syntax) to match documents by passing the `lang` argument with the value `koncorde`.  
+Koncorde filters will be translated into an Elasticsearch query.  
+
+::: warning
+Koncorde `bool` operator and `regexp` clause are not supported for search queries.
+:::
+
 If left empty, the result will return all available API keys of the currently loggued user.
 
 ### options
@@ -40,6 +49,7 @@ Additional query options
 | ---------- | ------------------ | ------------ |
 | `from`     | <pre>number</pre><br/>(`0`)     | Offset of the first document to fetch   |
 | `size`     | <pre>number</pre><br/>(`10`)    | Maximum number of documents to retrieve per page     |
+| `lang`     | <pre>string</pre>               | Specify the query language to use. By default, it's `elasticsearch` but `koncorde` can also be used. <SinceBadge version="auto-version"/> |
 
 ## Resolves
 
@@ -60,4 +70,10 @@ Each object of the `hits` array has the following properties:
 
 ## Usage
 
-<<< ./snippets/search-api-keys.js
+With the [ElasticSearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/query-dsl.html) syntax.
+
+<<< ./snippets/search-api-keys-es.js
+
+With the [Koncorde Filters DSL](/core/2/api/koncorde-filters-syntax) syntax.
+
+<<< ./snippets/search-api-keys-koncorde.js

doc/7/controllers/auth/search-api-keys/snippets/search-api-keys.test.yml → doc/7/controllers/auth/search-api-keys/snippets/search-api-keys-es.test.yml

@@ -1,4 +1,4 @@
-name: auth#searchApiKeys
+name: auth#searchApiKeys-es
 description: Searches API keys for the currently loggued user.
 hooks:
   before: >

doc/7/controllers/auth/search-api-keys/snippets/search-api-keys-koncorde.js

@@ -0,0 +1,66 @@
+try {
+  const promises = [];
+
+  // Create some API keys for user "jared.doe"
+  promises.push(
+    kuzzle.security.createApiKey('jared.doe', 'Sigfox API key'));
+  promises.push(
+    kuzzle.security.createApiKey('jared.doe', 'LoRa 6 month API key', {
+      expiresIn: 36000
+    }));
+  promises.push(
+    kuzzle.security.createApiKey('jared.doe', 'LoRa permanent API key', {
+      expiresIn: 42000, refresh: 'wait_for'
+    }));
+
+  await Promise.all(promises);
+
+  // Log as "jared.doe"
+  await kuzzle.auth.login('local', { username: 'jared.doe', password: 'password' });
+
+  const results = await kuzzle.auth.searchApiKeys({
+    or: [
+      {
+        equals: {
+          ttl: 42000
+        }
+      },
+      {
+        equals: {
+          ttl: 36000
+        },
+      }
+    ]
+  }, { lang: 'koncorde' });
+
+  console.log(results);
+  /*
+  {
+    "total": 2,
+    "hits": [
+      {
+        "_id": "znEwbG8BJASM_0-bWU-q",
+        "_source": {
+          "description": "LoRa permanent API key",
+          "userId": "jared.doe",
+          "expiresAt": 31557600000,
+          "ttl": 420000
+        }
+      },
+      {
+        "_id": "zXEwbG8BJASM_0-bWU-q",
+        "_source": {
+          "description": "LoRa 1 year API key",
+          "userId": "jared.doe",
+          "expiresAt": 31557600000,
+          "ttl": 420000
+        }
+      }
+    ]
+  }
+  */
+
+  console.log(`Found ${results.total} API keys.`);
+} catch (e) {
+  console.error(e);
+}

doc/7/controllers/auth/search-api-keys/snippets/search-api-keys-koncorde.test.yml

@@ -0,0 +1,20 @@
+name: auth#searchApiKeys-koncorde
+description: Searches API keys for the currently loggued user.
+hooks:
+  before: >
+    curl --fail -H "Content-type: application/json" -d '{
+      "content": {
+        "profileIds": ["default"]
+      },
+      "credentials": {
+        "local": {
+          "username": "jared.doe",
+          "password": "password"
+        }
+      }
+    }' "kuzzle:7512/users/jared.doe/_create?refresh=wait_for"
+  after:
+    curl -XDELETE kuzzle:7512/users/jared.doe
+template: default
+expected:
+  - Found 2 API keys.

doc/7/controllers/bulk/delete-by-query/snippets/delete-by-query.test.yml

@@ -15,6 +15,6 @@ hooks:
     done
 
     curl -XPOST kuzzle:7512/nyc-open-data/yellow-taxi/_refresh
-  after:
+
 template: default
 expected: Successfully deleted 5 documents

doc/7/controllers/document/delete-by-query/index.md

@@ -11,6 +11,15 @@ Deletes documents matching the provided search query.
 
 Kuzzle uses the [ElasticSearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/query-dsl.html) syntax.
 
+<SinceBadge version="auto-version"/>
+
+This method also supports the [Koncorde Filters DSL](/core/2/api/koncorde-filters-syntax) to match documents by passing the `lang` argument with the value `koncorde`.  
+Koncorde filters will be translated into an Elasticsearch query.  
+
+::: warning
+Koncorde `bool` operator and `regexp` clause are not supported for search queries.
+:::
+
 An empty or null query will match all documents in the collection.
 
 <br/>
@@ -34,11 +43,19 @@ Additional query options
 | ---------- | ------------------------------- | ---------------------------------------------------------------------------------- |
 | `queuable` | <pre>boolean</pre><br/>(`true`) | If true, queues the request during downtime, until connected to Kuzzle again       |
 | `refresh`  | <pre>string</pre><br/>(`""`)    | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) |
+| `source`   | <pre>boolean</pre>              | if set to `true` Kuzzle will return each deleted document body in the response |
+| `lang`     | <pre>string</pre>               | Specify the query language to use. By default, it's `elasticsearch` but `koncorde` can also be used. <SinceBadge version="auto-version"/> |
 
 ## Resolves
 
 Resolves to an array of strings containing the deleted document ids.
 
 ## Usage
 
-<<< ./snippets/delete-by-query.js
+With the [ElasticSearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/query-dsl.html) syntax.
+
+<<< ./snippets/delete-by-query-es.js
+
+With the [Koncorde Filters DSL](/core/2/api/koncorde-filters-syntax) syntax.
+
+<<< ./snippets/delete-by-query-koncorde.js

doc/7/controllers/document/delete-by-query/snippets/delete-by-query.js → doc/7/controllers/document/delete-by-query/snippets/delete-by-query-es.js

@@ -3,9 +3,7 @@ try {
     'nyc-open-data',
     'yellow-taxi',
     {
-      query: {
-        term: { capacity: 7 }
-      }
+      query: { term: { capacity: 7 } }
     }
   );
 

doc/7/controllers/document/delete-by-query/snippets/delete-by-query.test.yml → doc/7/controllers/document/delete-by-query/snippets/delete-by-query-es.test.yml

@@ -1,4 +1,4 @@
-name: document#deleteByQuery
+name: document#deleteByQuery-es
 description: Delete documents matching query
 hooks:
   before: |

doc/7/controllers/document/delete-by-query/snippets/delete-by-query-koncorde.js

@@ -0,0 +1,14 @@
+try {
+  const deleted = await kuzzle.document.deleteByQuery(
+    'nyc-open-data',
+    'yellow-taxi', {
+      query: {
+        equals: { capacity: 7 }
+      }
+    }, { lang: 'koncorde' }
+  );
+
+  console.log(`Successfully deleted ${deleted.length} documents`);
+} catch (error) {
+  console.error(error.message);
+}

doc/7/controllers/document/delete-by-query/snippets/delete-by-query-koncorde.test.yml

@@ -0,0 +1,20 @@
+name: document#deleteByQuery-koncorde
+description: Delete documents matching query
+hooks:
+  before: |
+    curl -XDELETE kuzzle:7512/nyc-open-data
+    curl -XPOST kuzzle:7512/nyc-open-data/_create
+    curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi
+
+    for i in  1 2 3 4 5; do
+      curl --fail -H "Content-type: application/json" -d '{"capacity": 4}' kuzzle:7512/nyc-open-data/yellow-taxi/_create
+    done
+
+    for i in  1 2 3 4 5; do
+      curl --fail -H "Content-type: application/json" -d '{"capacity": 7}' kuzzle:7512/nyc-open-data/yellow-taxi/_create
+    done
+
+    curl -XPOST kuzzle:7512/nyc-open-data/yellow-taxi/_refresh
+  after:
+template: default
+expected: Successfully deleted 5 documents

doc/7/controllers/document/search/index.md

@@ -26,6 +26,14 @@ It can lead to memory leaks if a scroll duration too great is provided, or if to
 You can restrict the scroll session maximum duration under the `services.storage.maxScrollDuration` configuration key.
 :::
 
+<SinceBadge version="auto-version"/>
+
+This method also supports the [Koncorde Filters DSL](/core/2/api/koncorde-filters-syntax) to match documents by passing the `lang` argument with the value `koncorde`.  
+Koncorde filters will be translated into an Elasticsearch query.  
+
+::: warning
+Koncorde `bool` operator and `regexp` clause are not supported for search queries.
+:::
 
 <br/>
 
@@ -50,6 +58,7 @@ Additional query options
 | `from`     | <pre>number</pre><br/>(`0`)     | Offset of the first document to fetch                                                                                                                                                                             |
 | `size`     | <pre>number</pre><br/>(`10`)    | Maximum number of documents to retrieve per page                                                                                                                                                                  |
 | `scroll`   | <pre>string</pre><br/>(`""`)    | When set, gets a forward-only cursor having its ttl set to the given value (ie `30s`; cf [elasticsearch time limits](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/common-options.html#time-units)) |
+| `lang`     | <pre>string</pre>      | Specify the query language to use. By default, it's `elasticsearch` but `koncorde` can also be used. <SinceBadge version="auto-version"/> |
 | `verb`     | <pre>string</pre>      | (HTTP only) Forces the verb of the route |
 
 #### verb
@@ -61,7 +70,7 @@ You can set the `verb` option to `GET` to force the SDK to use the GET API inste
 
 ### Optional:
 
-- `query`: the search query itself, using the [ElasticSearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/query-dsl.html) syntax.
+- `query`: the search query itself, using the [ElasticSearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/query-dsl.html) or the [Koncorde Filters DSL](/core/2/api/koncorde-filters-syntax) syntax.
 - `aggregations`: control how the search results should be [aggregated](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/search-aggregations.html)
 - `sort`: contains a list of fields, used to [sort search results](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/search-request-sort.html), in order of importance.
 
@@ -73,4 +82,10 @@ Resolves to a [SearchResult](/sdk/js/7/core-classes/search-result) object.
 
 ## Usage
 
-<<< ./snippets/search.js
+With the [ElasticSearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/query-dsl.html) syntax.
+
+<<< ./snippets/search-es.js
+
+With the [Koncorde Filters DSL](/core/2/api/koncorde-filters-syntax) syntax.
+
+<<< ./snippets/search-koncorde.js

doc/7/controllers/document/search/snippets/search.test.yml → doc/7/controllers/document/search/snippets/search-es.test.yml

@@ -1,4 +1,4 @@
-name: document#search
+name: document#search-with-es
 description: Search for documents
 hooks:
   before: |

doc/7/controllers/document/search/snippets/search-koncorde.js

@@ -0,0 +1,60 @@
+const suv = { category: 'suv' };
+const limousine = { category: 'limousine' };
+
+try {
+  const requests = [];
+
+  for (let i = 0; i < 5; i++) {
+    requests.push(kuzzle.document.create('nyc-open-data', 'yellow-taxi', suv));
+  }
+  for (let i = 0; i < 10; i++) {
+    requests.push(kuzzle.document.create('nyc-open-data', 'yellow-taxi', limousine));
+  }
+  await Promise.all(requests);
+
+  await kuzzle.collection.refresh('nyc-open-data', 'yellow-taxi');
+
+  const options = { lang: 'koncorde' };
+
+  const results = await kuzzle.document.search(
+    'nyc-open-data',
+    'yellow-taxi',
+    {
+      query: {
+        equals: {
+          category: 'suv'
+        }
+      }
+    },
+    options
+  );
+
+  console.log(results);
+  /*
+    {
+      "aggregations": undefined,
+      "hits": [
+        {
+          "_id": "AWgi6A1POQUM6ucJ3q06",
+          "_score": 0.046520017,
+          "_source": {
+            "category": "suv",
+            "_kuzzle_info": {
+              "author": "-1",
+              "createdAt": 1546773859655,
+              "updatedAt": null,
+              "updater": null
+            }
+          }
+        },
+        ...
+      ]
+    },
+    "total": 5,
+    "fetched": 5,
+    "scroll_id": undefined
+  */
+  console.log(`Successfully retrieved ${results.total} documents`);
+} catch (error) {
+  console.error(error.message);
+}

doc/7/controllers/document/search/snippets/search-koncorde.test.yml

@@ -0,0 +1,10 @@
+name: document#search-with-koncorde
+description: Search for documents
+hooks:
+  before: |
+    curl -XDELETE kuzzle:7512/nyc-open-data
+    curl -XPOST kuzzle:7512/nyc-open-data/_create
+    curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi
+  after:
+template: default
+expected: Successfully retrieved 5 documents

doc/7/controllers/document/update-by-query/index.md

@@ -11,6 +11,15 @@ Updates documents matching the provided search query.
 
 Kuzzle uses the [ElasticSearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/7.4/query-dsl.html) syntax.
 
+<SinceBadge version="auto-version"/>
+
+This method also supports the [Koncorde Filters DSL](/core/2/api/koncorde-filters-syntax) to match documents by passing the `lang` argument with the value `koncorde`.  
+Koncorde filters will be translated into an Elasticsearch query.  
+
+::: warning
+Koncorde `bool` operator and `regexp` clause are not supported for search queries.
+:::
+
 An empty or null query will match all documents in the collection.
 
 <br/>
@@ -37,7 +46,7 @@ Additional query options.
 | ----------------- | ------------------------------- | ---------------------------------------------------------------------------------- |
 | `refresh`         | <pre>string</pre><br/>(`""`)    | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) |
 | `source`          | <pre>boolean</pre><br/>(`false`)| If true, returns the updated document inside the response
-
+| `lang`            | <pre>string</pre>               | Specify the query language to use. By default, it's `elasticsearch` but `koncorde` can also be used. <SinceBadge version="auto-version"/> |
 ## Resolves
 
 Returns an object containing 2 arrays: `successes` and `errors`
@@ -61,4 +70,10 @@ Each errored document is an object of the `errors` array with the following prop
 
 ## Usage
 
-<<< ./snippets/update-by-query.js
+With the [ElasticSearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/query-dsl.html) syntax.
+
+<<< ./snippets/update-by-query-es.js
+
+With the [Koncorde Filters DSL](/core/2/api/koncorde-filters-syntax) syntax.
+
+<<< ./snippets/update-by-query-koncorde.js