Queries and Searches

Recipes for searching and retrieving data in OSDU.

Search API vs Storage API

The search API only returns indexed fields — not the complete object. If fields are missing from search results, use the storage API with the object's ID to get the full record.

CLIPython SDKSearch API (HTTP body)

The --filter option uses jmespath. See also the community search pages.

List records and schemas

osdu list records                                            # All record types and counts
osdu schema list                                             # All schema types
osdu schema list --filter [totalCount]                       # Total schema count

Search by kind

osdu search kind 'osdu:wks:master-data--Well:1.0.0' --filter results[*].data.FacilityName --limit 200
osdu search kind 'eqnr:smda-api-v2.0:fields:1.0.0' --filter totalCount

Filter columns

osdu search kind eqnr:smda-api-v2.0:wellheaders:1.0.0 --filter "results[*].data.{id:wellboreUuid,data:drilledInLicenseIdentifier}"
osdu search kind osdu:wks:master-data--Well:1.0.0 --filter "results[*].{id:id,data:data.FacilityName}" --limit 200
osdu search kind osdu:wks:master-data--Wellbore:1.0.0 --filter "results[*].{id:id,FacilityName:data.FacilityName,Parent:ancestry.parents[*]}" --limit 200

JSON output

osdu search kind osdu:wks:master-data--Wellbore:1.1.0 --filter "results[*].{id:id,FacilityName:data.FacilityName,alias:data.NameAliases}" -o json --limit 1000

Query string search

osdu search query -q "data.fieldIdentifier:'JOHANSVERDRUP'"
osdu search query -q 'data.fieldIdentifier:"TROLL"' -k "eqnr:smda-api-v2.0:wellheaders:1.0.0" -o json

Storage queries (full objects)

osdu storage get --id "dev:master-data--Well:cec9ddcc-6ca7-11ed-9855-367dda495db0" -o json
osdu storage get --id 'dev:wellheaders:ad215042-115f-2b7e-e053-c818a488c79a' -o json --filter "records[*].{osdu_id:id,wellbore_name:data.uniqueWellboreIdentifier,field:data.fieldIdentifier}"

Custom JSON output

osdu search query -k "osdu:wks:master-data--Wellbore:1.1.0" -id 'dev:master-data--Wellbore:77817912-7099-11ed-97ff-367dda495db0' -o json --filter "results[*].{wbid:id,fieldid:data.GeoContexts[*].FieldID}"

Switch config

osdu config default -c C:\Users\me\.osducli\config_dev

See Configuration Files for ready-made configs per environment.

Shell tips

PowerShell

osdu list records | Select -First 12          # Limit output
osdu list records | Select-String well,field  # Filter by keyword
osdu list records | clip                      # Copy to clipboard

Unix shell (Linux/Mac/WSL)

osdu list records | grep -i trajectory        # Filter output
osdu list records | pbcopy                    # Copy to clipboard (macOS)
watch -n 10 'osdu list records | grep Coordinate'  # Monitor every 10s

from urllib.parse import urljoin

# Search by kind
KIND = "osdu:wks:master-data--Well:1.1.0"
_url = urljoin(osdu_service.client.server_url, "search/v2/query")
payload = {"kind": KIND, "query": "", "limit": 1}
response = osdu_service.client.post_returning_json(url=_url, data=payload)

# Get a schema
_url = urljoin(osdu_service.client.server_url, f"schema-service/v1/schema/{KIND}")
schema = osdu_service.client.get_returning_json(url=_url)

# Extract values from results
theid = response["results"][0]["id"]
theids = [rec["id"] for rec in response["results"]]

# Storage query (full object)
full_record = osdu_service.get_storage('dev:master-data--Well:cec9ddcc-6ca7-11ed-9855-367dda495db0')

These are the JSON bodies you send to the /search/v2/query endpoint.

By kind

{"kind": "{{data-partition-id}}:wks:reference-data--UnitOfMeasure:1.0.0", "query": "*", "limit": 100}

By ID with specific return fields

{"kind": "*:*:*:*", "query": "id:(\"opendes:reference-data--FacilityType:WELL\")", "returnedFields": ["id", "version"]}

By Attribution Authority

{"kind": "*:*:*:*", "query": "data.AttributionAuthority:(\"Equinor\")"}

Null value check

{"kind": "*:*:*:*", "query": "tags.exportControl.keyword: null"}

Aggregate by field

{"kind": "*:*:*:*", "aggregateBy": "tags.exportControl", "limit": 1}

Geo-spatial bounding box

{
  "kind": "*:*:master-data--Well:*",
  "spatialFilter": {
    "field": "data.SpatialLocation.Wgs84Coordinates",
    "byBoundingBox": {
      "topLeft": {"latitude": 72.61, "longitude": 20.0},
      "bottomRight": {"latitude": 72.34, "longitude": 20.47}
    }
  }
}

By ACL owners

{"kind": "*:*:*:*", "query": "acl.owners: \"replace-acl-owner-group-here\""}

Nested queries (inside arrays)

{"kind": "osdu:wks:master-data--Wellbore:1.1.0", "query": "nested(data.GeoContexts, (\"FieldID\"= \"dev:master-data--Field:c54295a6-708e-11ed-aa24-367dda495db0:\"))", "returnedFields": ["id"]}

Time-range

{"kind": "*:*:*:*", "query": "createTime:[2023-01-01 TO 2023-12-31]"}

---

Last update: 2026-02-27