... | ... | @@ -7,6 +7,7 @@ |
|
|
* [Wildcard](#wildcard)
|
|
|
* [Field-match query](#field-match-query)
|
|
|
* [Boolean operators](#boolean-operators)
|
|
|
* [Fuzzy search](#fuzzy-search)
|
|
|
* [Filters](#filters)
|
|
|
* [Pagination](#pagination)
|
|
|
* [Offset](#offset)
|
... | ... | @@ -33,11 +34,10 @@ The request must have the following headers: |
|
|
~~~
|
|
|
Authorization: Bearer {access_token}
|
|
|
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>.
|
|
|
Also the default `partition` is `opendes`.
|
|
|
You should get the access_token during authorization.
|
|
|
|
|
|
## Request body
|
|
|
|
... | ... | @@ -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**
|
|
|
|
... | ... | @@ -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"] |
|
|
|
| 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"]} |
|
|
|
| spatialFilter | Filters resources located in an area | |
|
|
|
| spatialFilter | Filters resources located in an area | See [below](#spatial-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
|
|
|
|
|
|
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'. |
|
|
|
|
|
#### 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**
|
|
|
|
... | ... | @@ -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
|
|
|
|
|
|
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: `\"`.
|
|
|
|
... | ... | @@ -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.
|
|
|
|
|
|
#### 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
|
|
|
|
|
|
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 |
|
|
**Example**
|
|
|
~~~json
|
|
|
{
|
|
|
"kind": "opendes:osdu:*:*",
|
|
|
"query": "(data.ResourceID:3687) AND (data.ResourceTypeID: \"srn:type:master-data/Wellbore:\")",
|
|
|
"offset": 10
|
|
|
"kind": "opendes:osdu:*:0.2.0",
|
|
|
"query": "data.Data.IndividualTypeProperties.WellID:\"srn:master-data/Well:3687:\"",
|
|
|
"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
|
|
|
|
|
|
The results can be sorted by a numeric or date field.
|
|
|
|
|
|
**Example**
|
|
|
~~~json
|
|
|
~~~
|
|
|
{
|
|
|
"kind": "opendes:osdu:well:*",
|
|
|
"query": "data.SpudDate:[1999-01-01 TO 1999-02-28]",
|
|
|
"kind": "opendes:osdu:wellbore-master:0.2.0",
|
|
|
"query": "data.Data.IndividualTypeProperties.FacilityName:\"BIR-02\" AND data.ResourceTypeID:\"srn:type:master-data/Wellbore\"",
|
|
|
"sort": {
|
|
|
"field": ["data.SpudDate"],
|
|
|
"order": ["ASC"]
|
|
|
},
|
|
|
"limit": 30
|
|
|
"field": ["Data.IndividualTypeProperties.SequenceNumber"],
|
|
|
"order": ["DESC"]
|
|
|
}
|
|
|
}
|
|
|
~~~
|
|
|
|
|
|
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:
|
|
|
> 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 |
|
|
A spatial query is specified in the `spatialFilter` parameter, with `spatialFilter.field` set to `data.Geolocation`.
|
|
|
|
|
|
> 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
|
|
|
|
... | ... | @@ -241,7 +272,7 @@ You can search for resources located within a bounding box. The coordinates of t |
|
|
**Example**
|
|
|
~~~json
|
|
|
{
|
|
|
"kind": "opendes:osdu:well:*",
|
|
|
"kind": "opendes:osdu:well:0.2.1",
|
|
|
"spatialFilter": {
|
|
|
"field": "data.GeoLocation",
|
|
|
"byBoundingBox": {
|
... | ... | @@ -265,7 +296,7 @@ You can search for resources located within a polygon. Describe a polygon by spe |
|
|
**Example**
|
|
|
~~~json
|
|
|
{
|
|
|
"kind": "opendes:osdu:*:*",
|
|
|
"kind": "opendes:osdu:*:0.2.1",
|
|
|
"query": "HOK",
|
|
|
"spatialFilter": {
|
|
|
"field": "data.GeoLocation",
|
... | ... | @@ -306,7 +337,7 @@ You can search for resources located within a certain distance of a point. Speci |
|
|
**Example**
|
|
|
~~~json
|
|
|
{
|
|
|
"kind": "opendes:osdu:well:*",
|
|
|
"kind": "opendes:osdu:well:0.2.1",
|
|
|
"spatialFilter": {
|
|
|
"field": "data.GeoLocation",
|
|
|
"byDistance": {
|
... | ... | @@ -327,12 +358,13 @@ Ranges can be queried for date, numeric or string fields. For inclusive ranges u |
|
|
**Example**
|
|
|
~~~json
|
|
|
{
|
|
|
"kind": "opendes:osdu:*:*",
|
|
|
"query": "data.SpudDate:[2012-01-01 TO 2012-12-31]"
|
|
|
}
|
|
|
~~~
|
|
|
|
|
|
> 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`.
|
|
|
|
|
|
#### Unbounded side
|
... | ... | |