Changes

Page history
Update OSDU Query Syntax authored by Dmitry Kniazev's avatar Dmitry Kniazev
Hide whitespace changes
Inline Side-by-side
Releases/R2.0/OSDU-Query-Syntax.md
View page @ 35b31922
...@@ -7,6 +7,7 @@ ...@@ -7,6 +7,7 @@
* [Wildcard](#wildcard) * [Wildcard](#wildcard)
* [Field-match query](#field-match-query) * [Field-match query](#field-match-query)
* [Boolean operators](#boolean-operators) * [Boolean operators](#boolean-operators)
* [Fuzzy search](#fuzzy-search)
* [Filters](#filters) * [Filters](#filters)
* [Pagination](#pagination) * [Pagination](#pagination)
* [Offset](#offset) * [Offset](#offset)
...@@ -33,11 +34,10 @@ The request must have the following headers: ...@@ -33,11 +34,10 @@ The request must have the following headers:
~~~ ~~~
Authorization: Bearer {access_token} Authorization: Bearer {access_token}
Content-Type: application/json Content-Type: application/json
data-partition-id: {partition} data-partition-id: bootcamp
~~~ ~~~
You should get the `access_token` as part of the authorization process <link is coming>. You should get the access_token during authorization.
Also the default `partition` is `opendes`.
## Request body ## Request body
...@@ -59,7 +59,7 @@ The request body should contain a JSON-style query. ...@@ -59,7 +59,7 @@ The request body should contain a JSON-style query.
} }
} }
~~~ ~~~
Note that all quotes are double-quotes, and that inner quotes must be escaped. Note that all quotes are double-quotes, and that internal quotes must be escaped.
**Parameters** **Parameters**
...@@ -74,10 +74,14 @@ The query body must contain `kind`; other parameters are optional. ...@@ -74,10 +74,14 @@ The query body must contain `kind`; other parameters are optional.
| returnedFields | The fields on which to project the results. | "returnedFields": ["data.ResourceTypeID", "kind"]​ | | returnedFields | The fields on which to project the results. | "returnedFields": ["data.ResourceTypeID", "kind"]​ |
| aggregateBy | Groups results by the specified field.​ | "aggregateBy": "kind"​ | | aggregateBy | Groups results by the specified field.​ | "aggregateBy": "kind"​ |
| sort | Allows you to add one or more sorts on specific fields | "sort": {"field": ["kind"], "order":["DESC"]}​ | | sort | Allows you to add one or more sorts on specific fields | "sort": {"field": ["kind"], "order":["DESC"]}​ |
| spatialFilter | Filters resources located in an area | | | spatialFilter | Filters resources located in an area | See [below](#spatial-queries) |
## Queries ## Queries
### Text indexing
When indexing data, OSDU Indexer service parse non-alphanumeric characters (dash, semicolon, etc.) as a space. In queries, such characters are also replaced by a space. So, the following text queries are equivalent: 'BIR-01' and 'BIR 01'.
### Text queries ### Text queries
The string to search for should be specified in the `query` parameter. The string to search for should be specified in the `query` parameter.
...@@ -96,7 +100,9 @@ This request searches for fields which contain text 'A05'. ...@@ -96,7 +100,9 @@ This request searches for fields which contain text 'A05'.
#### Wildcard #### Wildcard
The API supports wildcard in text search. Use ? to replace a single character, and * to replace zero or more characters. The API supports wildcard in text search. Use `?` to replace a single character, and `*` to replace zero or more characters. A query term cannot start with a wildcard.
> Note: Wildcard does not work with `UWI` and `UWBI`, since they are numeric fields.
**Examples** **Examples**
...@@ -114,9 +120,18 @@ The API supports wildcard in text search. Use ? to replace a single character, a ...@@ -114,9 +120,18 @@ The API supports wildcard in text search. Use ? to replace a single character, a
} }
~~~ ~~~
When querying a multi-term phase with a wildcard, use the [AND operator](#boolean-operators). E.g., the following query will find term 'BIR' and terms starting with zero: '0?':
~~~json
{
"kind": "opendes:osdu:*:*",
"query": "data.Data.IndividualTypeProperties.FacilityName:(BIR AND 0?)"
}
~~~
#### Field-match query #### Field-match query
A field in the document can be searched by using `<field-name>:<value>`. A field in the document can be searched by using `<field-name>:<value>`. To have several fields matched, use [Booleans](#boolean-operators).
String values with special characters such as `:` or `/` should be put in escaped quotes: `\"`. String values with special characters such as `:` or `/` should be put in escaped quotes: `\"`.
...@@ -133,7 +148,7 @@ This request searches for resources which contain the field `"data.ResourceID": ...@@ -133,7 +148,7 @@ This request searches for resources which contain the field `"data.ResourceID":
#### Boolean operators #### Boolean operators
The API supports AND and OR operators. Use them to combine field or values. The API supports AND and OR operators. Use them to combine field or values.
Multiple terms or clauses can be grouped together with parentheses. Multiple terms or clauses can be grouped together with parentheses.
...@@ -147,6 +162,23 @@ Multiple terms or clauses can be grouped together with parentheses. ...@@ -147,6 +162,23 @@ Multiple terms or clauses can be grouped together with parentheses.
This request searches for master-data wells with the 8690 or 8438 ResourceID. This request searches for master-data wells with the 8690 or 8438 ResourceID.
#### Fuzzy search
In fuzzy search, the half of characters of the query string can be modified (added, removed, or replaced). E.g., the "ab" query returns "ba", "ac", "cb", etc. To do a fuzzy search, use the tilde symbol `~` at the end of a string.
**Example**
~~~json
{
"kind": "opendes:osdu:*:0.2.1",
"query": "data.WellName:EMM~",
"limit":30
}
~~~
This request returns resources with the WellName containing EMM, EMO, EEM, OMM, EWM, EMC, ERM, etc.
> Note: The `WellName` field is valid only in the **0.2.1** schema.
### Filters ### Filters
Return fields in results can be filtered. Specify the list of fields in the `returnedFields` parameter. Return fields in results can be filtered. Specify the list of fields in the `returnedFields` parameter.
...@@ -188,32 +220,31 @@ The starting offset of return results can be specified in the `offset` parameter ...@@ -188,32 +220,31 @@ The starting offset of return results can be specified in the `offset` parameter
**Example** **Example**
~~~json ~~~json
{ {
"kind": "opendes:osdu:*:*", "kind": "opendes:osdu:*:0.2.0",
"query": "(data.ResourceID:3687) AND (data.ResourceTypeID: \"srn:type:master-data/Wellbore:\")", "query": "data.Data.IndividualTypeProperties.WellID:\"srn:master-data/Well:3687:\"",
"offset": 10 "offset": 1
} }
~~~ ~~~
This request returns the second page of the results for master-data wellbores with the 3687 ResourceID. This request returns the second and third wellbores of the 3687 well.
### Sorting results ### Sorting results
The results can be sorted by a numeric or date field. The results can be sorted by a numeric or date field.
**Example** **Example**
~~~json ~~~
{ {
"kind": "opendes:osdu:well:*", "kind": "opendes:osdu:wellbore-master:0.2.0",
"query": "data.SpudDate:[1999-01-01 TO 1999-02-28]", "query": "data.Data.IndividualTypeProperties.FacilityName:\"BIR-02\" AND data.ResourceTypeID:\"srn:type:master-data/Wellbore\"",
"sort": { "sort": {
"field": ["data.SpudDate"], "field": ["Data.IndividualTypeProperties.SequenceNumber"],
"order": ["ASC"] "order": ["DESC"]
}, }
"limit": 30
} }
~~~ ~~~
This request returns the first 30 wells spudded in January or February 1999; the results are sorted chronologically. This request returns wellbores of BIR-02 well; the results are sorted the wellbore sequence number.
> Note: > Note:
> The `data.SpudDate` field is valid only in the `0.2.1` schema. > The `data.SpudDate` field is valid only in the `0.2.1` schema.
...@@ -232,7 +263,7 @@ The API supports geo-spatial search for resources within an area of a rectangula ...@@ -232,7 +263,7 @@ The API supports geo-spatial search for resources within an area of a rectangula
A spatial query is specified in the `spatialFilter` parameter, with `spatialFilter.field` set to `data.Geolocation`. A spatial query is specified in the `spatialFilter` parameter, with `spatialFilter.field` set to `data.Geolocation`.
> Note: > Note:
> Spatial queries are valid only in the `0.2.1` schema. > Spatial queries are valid only in the **0.2.1** schema.
#### Bounding Box #### Bounding Box
...@@ -241,7 +272,7 @@ You can search for resources located within a bounding box. The coordinates of t ...@@ -241,7 +272,7 @@ You can search for resources located within a bounding box. The coordinates of t
**Example** **Example**
~~~json ~~~json
{ {
"kind": "opendes:osdu:well:*", "kind": "opendes:osdu:well:0.2.1",
"spatialFilter": { "spatialFilter": {
"field": "data.GeoLocation", "field": "data.GeoLocation",
"byBoundingBox": { "byBoundingBox": {
...@@ -265,7 +296,7 @@ You can search for resources located within a polygon. Describe a polygon by spe ...@@ -265,7 +296,7 @@ You can search for resources located within a polygon. Describe a polygon by spe
**Example** **Example**
~~~json ~~~json
{ {
"kind": "opendes:osdu:*:*", "kind": "opendes:osdu:*:0.2.1",
"query": "HOK", "query": "HOK",
"spatialFilter": { "spatialFilter": {
"field": "data.GeoLocation", "field": "data.GeoLocation",
...@@ -306,7 +337,7 @@ You can search for resources located within a certain distance of a point. Speci ...@@ -306,7 +337,7 @@ You can search for resources located within a certain distance of a point. Speci
**Example** **Example**
~~~json ~~~json
{ {
"kind": "opendes:osdu:well:*", "kind": "opendes:osdu:well:0.2.1",
"spatialFilter": { "spatialFilter": {
"field": "data.GeoLocation", "field": "data.GeoLocation",
"byDistance": { "byDistance": {
...@@ -327,12 +358,13 @@ Ranges can be queried for date, numeric or string fields. For inclusive ranges u ...@@ -327,12 +358,13 @@ Ranges can be queried for date, numeric or string fields. For inclusive ranges u
**Example** **Example**
~~~json ~~~json
{ {
"kind": "opendes:osdu:*:*",
"query": "data.SpudDate:[2012-01-01 TO 2012-12-31]" "query": "data.SpudDate:[2012-01-01 TO 2012-12-31]"
} }
~~~ ~~~
> Note: > Note:
> The `data.SpudDate` field is valid only in the `0.2.1` schema. > The `data.SpudDate` field is valid only in the **0.2.1** schema.
> In a date field, you can specify a year `YYYY`, a month `YYYY-MM`, or a day `YYYY-MM-DD`. > In a date field, you can specify a year `YYYY`, a month `YYYY-MM`, or a day `YYYY-MM-DD`.
#### Unbounded side #### Unbounded side
... ...
......