|
|
|
## Table of contents
|
|
|
|
|
|
|
|
- [Headers](#headers)
|
|
|
|
- [Request body](#request-body)
|
|
|
|
- [Queries](#queries)
|
|
|
|
* [Text queries](#text-queries)
|
|
|
|
* [Wildcard](#wildcard)
|
|
|
|
* [Field-match query](#field-match-query)
|
|
|
|
* [Boolean operators](#boolean-operators)
|
|
|
|
* [Filters](#filters)
|
|
|
|
* [Pagination](#pagination)
|
|
|
|
* [Offset](#offset)
|
|
|
|
* [Sorting results](#sorting-results)
|
|
|
|
* [Spatial queries](#spatial-queries)
|
|
|
|
* [Bounding box](#bounding-box)
|
|
|
|
* [Polygon](#polygon)
|
|
|
|
* [Distance](#distance)
|
|
|
|
* [Range queries](#range-queries)
|
|
|
|
* [Unbounded side](#unbounded-side)
|
|
|
|
* [Aggregating results](#aggregating-results)
|
|
|
|
|
|
|
|
|
|
|
|
The OSDU Search API supports full-text and field-match search, filters and pagination, range queries, and spatial search.
|
|
|
|
|
|
|
|
The method for all requests is POST.
|
|
|
|
|
|
|
|
`POST / HTTP/1.1 Host: https://<server-name>/api/search/v2/query`
|
|
|
|
|
|
|
|
## Headers
|
|
|
|
|
|
|
|
The request must have the following headers:
|
|
|
|
|
|
|
|
~~~
|
|
|
|
Authorization: Bearer {access_token}
|
|
|
|
Content-Type: application/json
|
|
|
|
data-partition-id: {partition}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
You should get the `access_token` as part of the authorization process <link is coming>.
|
|
|
|
Also the default `partition` is `opendes`.
|
|
|
|
|
|
|
|
## Request body
|
|
|
|
|
|
|
|
The request body should contain a JSON-style query.
|
|
|
|
|
|
|
|
**Sample query**
|
|
|
|
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"kind": "opendes:osdu:well:*",
|
|
|
|
"query": "data.ResourceID:\"srn:master-data/Wellbore:3687\"",
|
|
|
|
"offset": 0,
|
|
|
|
"limit": 1,
|
|
|
|
"returnedFields": ["data.ResourceTypeID", "kind"],
|
|
|
|
"aggregateBy": "kind",
|
|
|
|
"sort": {
|
|
|
|
"field": ["type"],
|
|
|
|
"order": ["DESC"]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
Note that all quotes are double-quotes, and that inner quotes must be escaped.
|
|
|
|
|
|
|
|
**Parameters**
|
|
|
|
|
|
|
|
The query body must contain `kind`; other parameters are optional.
|
|
|
|
|
|
|
|
| Parameter| Description | Example |
|
|
|
|
| ------ | ------ | ------ |
|
|
|
|
| kind | The kind of the records to search for. "kind" is formatted as \<namespace>:\<source>:\<entityType>:\<schemaVersion>. You can use wildcard in any of the four semicolon-separated parts. | "kind": "opendes:osdu:well:2.0.0" |
|
|
|
|
| query | The query string in [Lucene query string syntax](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html) | "query": "A05*" |
|
|
|
|
| offset | The starting offset from which to return results | "offset": 0 |
|
|
|
|
| limit | The maximum number of results to return from the given offset (default: 10, max: 100). | "limit": 10 |
|
|
|
|
| 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 | |
|
|
|
|
|
|
|
|
## Queries
|
|
|
|
|
|
|
|
### Text queries
|
|
|
|
|
|
|
|
The string to search for should be specified in the `query` parameter.
|
|
|
|
|
|
|
|
The API supports [Lucene Query Syntax](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html) providing wildcard, Boolean operators and fuzzy search.
|
|
|
|
|
|
|
|
**Example**
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"kind": "opendes:osdu:*:*",
|
|
|
|
"query": "A05"
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
**Examples**
|
|
|
|
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"kind": "opendes:osdu:*:*",
|
|
|
|
"query": "A?8"
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"kind": "opendes:osdu:*:*",
|
|
|
|
"query": "data.ResourceID:100*"
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
#### Field-match query
|
|
|
|
|
|
|
|
A field in the document can be searched by using `<field-name>:<value>`.
|
|
|
|
|
|
|
|
String values with special characters such as `:` or `/` should be put in escaped quotes: `\"`.
|
|
|
|
|
|
|
|
**Example**
|
|
|
|
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"kind": "opendes:osdu:*:*",
|
|
|
|
"query": "data.ResourceID:8690"
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
This request searches for resources which contain the field `"data.ResourceID": "8690"`.
|
|
|
|
|
|
|
|
#### Boolean operators
|
|
|
|
|
|
|
|
The API supports AND and OR operators. Use them to combine field or values.
|
|
|
|
|
|
|
|
Multiple terms or clauses can be grouped together with parentheses.
|
|
|
|
|
|
|
|
**Example**
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"kind": "opendes:osdu:*:*",
|
|
|
|
"query": "(data.ResourceID:(8690 OR 8438)) AND (data.ResourceTypeID:\"srn:type:master-data/Well:\")"
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
This request searches for master-data wells with the 8690 or 8438 ResourceID.
|
|
|
|
|
|
|
|
### Filters
|
|
|
|
|
|
|
|
Return fields in results can be filtered. Specify the list of fields in the `returnedFields` parameter.
|
|
|
|
|
|
|
|
We recommend that you use filtering whenever possible, to increase the server performance.
|
|
|
|
|
|
|
|
**Example**
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"kind": "opendes:osdu:welllog-wpc:*",
|
|
|
|
"query": "data.ResourceTypeID: \"srn:type:work-product-component/WellLog:\"",
|
|
|
|
"returnedFields": ["data.ResourceID", "data.Curves"]
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
The results contain only two fields.
|
|
|
|
|
|
|
|
### Pagination
|
|
|
|
|
|
|
|
The default number of return results is 10. You can change it by specifying the `limits` parameter. The maximum is 100. `"limits": 0` means the default value of results will be returned.
|
|
|
|
|
|
|
|
The total number of results is returned in `totalCount`.
|
|
|
|
|
|
|
|
**Example**
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"kind": "opendes:osdu:*:*",
|
|
|
|
"query": "(data.ResourceID:3687) AND (data.ResourceTypeID: \"srn:type:master-data/Wellbore:\")",
|
|
|
|
"limit": 1
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
This request returns the first wellbore from the results.
|
|
|
|
|
|
|
|
#### Offset
|
|
|
|
|
|
|
|
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
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
This request returns the second page of the results for master-data wellbores with the 3687 ResourceID.
|
|
|
|
|
|
|
|
### 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]",
|
|
|
|
"sort": {
|
|
|
|
"field": ["data.SpudDate"],
|
|
|
|
"order": ["ASC"]
|
|
|
|
},
|
|
|
|
"limit": 30
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
This request returns the first 30 wells spudded in January or February 1999; the results are sorted chronologically.
|
|
|
|
|
|
|
|
> Note:
|
|
|
|
> The `data.SpudDate` field is valid only in the `0.2.1` schema.
|
|
|
|
|
|
|
|
**Parameters**
|
|
|
|
|
|
|
|
| Parameter | Description |
|
|
|
|
| ----- | ----- |
|
|
|
|
| sort.field | Parameter to sort by |
|
|
|
|
| sort.order | Sorting order: `ASC` or `DESC` |
|
|
|
|
|
|
|
|
### Spatial queries
|
|
|
|
|
|
|
|
The API supports geo-spatial search for resources within an area of a rectangular, polygonal, or circular shape.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
#### Bounding Box
|
|
|
|
|
|
|
|
You can search for resources located within a bounding box. The coordinates of the top left and bottom right points should be specified. The top left point should be located to the the north-west of the bottom right point.
|
|
|
|
|
|
|
|
**Example**
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"kind": "opendes:osdu:well:*",
|
|
|
|
"spatialFilter": {
|
|
|
|
"field": "data.GeoLocation",
|
|
|
|
"byBoundingBox": {
|
|
|
|
"topLeft": {
|
|
|
|
"longitude": 4.9493408203125,
|
|
|
|
"latitude": 52.859180945520826
|
|
|
|
},
|
|
|
|
"bottomRight": {
|
|
|
|
"longitude": 5.1580810546875,
|
|
|
|
"latitude": 52.75956761546834
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
#### Polygon
|
|
|
|
|
|
|
|
You can search for resources located within a polygon. Describe a polygon by specifying the list of points.
|
|
|
|
|
|
|
|
**Example**
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"kind": "opendes:osdu:*:*",
|
|
|
|
"query": "HOK",
|
|
|
|
"spatialFilter": {
|
|
|
|
"field": "data.GeoLocation",
|
|
|
|
"byGeoPolygon": {
|
|
|
|
"coordinates": [
|
|
|
|
{
|
|
|
|
"longitude": 5.1580810546875,
|
|
|
|
"latitude": 52.859180945520826
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"longitude": 4.9493408203125,
|
|
|
|
"latitude": 52.75956761546834
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"longitude": 5.064697265625,
|
|
|
|
"latitude": 52.579688026538726
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"longitude": 5.372314453125,
|
|
|
|
"latitude": 52.68970242806752
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"longitude": 5.1580810546875,
|
|
|
|
"latitude": 52.859180945520826
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
},
|
|
|
|
"offset": 0,
|
|
|
|
"limit": 30
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
#### Distance
|
|
|
|
|
|
|
|
You can search for resources located within a certain distance of a point. Specify the coordinates of the point, and the distance in meters.
|
|
|
|
|
|
|
|
**Example**
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"kind": "opendes:osdu:well:*",
|
|
|
|
"spatialFilter": {
|
|
|
|
"field": "data.GeoLocation",
|
|
|
|
"byDistance": {
|
|
|
|
"coordinate": {
|
|
|
|
"longitude": 5.1580810546875,
|
|
|
|
"latitude": 52.859180945520826
|
|
|
|
},
|
|
|
|
"distance": 10000
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
### Range queries
|
|
|
|
|
|
|
|
Ranges can be queried for date, numeric or string fields. For inclusive ranges use square brackets `[min TO max]` and curly brackets `{min TO max}` for exclusive ranges.
|
|
|
|
|
|
|
|
**Example**
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"query": "data.SpudDate:[2012-01-01 TO 2012-12-31]"
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
> Note:
|
|
|
|
> 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
|
|
|
|
|
|
|
|
Ranges with one side unbounded can use the following syntax:
|
|
|
|
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"kind": "opendes:osdu:welllog-wpc:*",
|
|
|
|
"query": "data.Data.IndividualTypeProperties.TopMeasuredDepth.Depth: >2200"
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
or
|
|
|
|
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"kind": "opendes:osdu:welllog-wpc:*",
|
|
|
|
"query": "data.Data.IndividualTypeProperties.TopMeasuredDepth.Depth:[2200 TO *]"
|
|
|
|
}
|
|
|
|
~~~
|
|
|
|
|
|
|
|
### Aggregating results
|
|
|
|
|
|
|
|
Results can be grouped by a parameter. Specify the aggregation parameter in `aggregateBy`. Results can only be aggregated by a non-nested field such as `kind`.
|
|
|
|
|
|
|
|
**Example**
|
|
|
|
~~~json
|
|
|
|
{
|
|
|
|
"kind": "opendes:osdu:*:*",
|
|
|
|
"query": "A05*",
|
|
|
|
"aggregateBy": "kind"
|
|
|
|
}
|
|
|
|
~~~ |
|
|
\ No newline at end of file |
