Advanced Search
Advanced search in B2INST v3#
Synopsis#
B2INST searches indexed instrument metadata, including names, descriptions, manufacturers,
owners, and community extension fields. This guide explains the query syntax used in the
web search box and the REST API’s q parameter.
The examples use illustrative metadata values. A valid query can return no results if no accessible record contains those values.
How to access the B2INST service#
The test service is available at b2inst-test.gwdg.de.
Searching in B2INST#
Enter a query in the web interface’s search box. You can also send the same query to
GET /api/records using the q parameter. For example, this request searches instrument
names for the phrase “soil moisture”:
curl --fail-with-body -sS --get 'https://b2inst-test.gwdg.de/api/records' \
--data-urlencode 'q=metadata.Name:"soil moisture"' \
--data-urlencode 'page=1' \
--data-urlencode 'size=10' \
--data-urlencode 'sort=bestmatch'
Use --get --data-urlencode to encode spaces, quotes, and other query characters
correctly. Omitting q lists records without a text query. See the
record search API for request and response details.
Underlying implementation#
The deployment uses OpenSearch 2. Search behaviour depends on each field’s index mapping: text fields support word and phrase searches, keyword fields support whole-value matching, and date fields support chronological ranges. A field being present in a record’s JSON does not by itself guarantee that it is searchable.
Text searches use the field’s analyser. The instrument text fields have no configured language stemming, so do not assume that a singular word also matches its plural. Search results can lag behind saved changes until indexing and an index refresh have completed. Unpublished changes remain draft content and are not part of published-record search results.
For further syntax details, see the OpenSearch query string reference. B2INST parses queries before passing them to OpenSearch; the examples below use syntax supported by the deployment’s parser.
Search records#
Published-record searches return records that the caller is allowed to read. Anonymous users can search public records. Signing in or providing an API bearer token can also allow access to restricted records, depending on the caller’s permissions.
By default, only the latest published version of each record is returned. Add
allversions=true to an API search to include older published versions. Drafts are
searched through the authenticated uploads search,
GET /api/user/records, which can return both drafts and published uploads.
Multiple keyword searches#
Without a field prefix, a query searches across the default searchable fields. Separate
terms are optional by default (OR). Use uppercase Boolean operators to make the
intended combination explicit, and parentheses to group expressions.
| Query | Meaning |
|---|---|
sensor temperature |
Match either term. |
sensor OR temperature |
Match either term explicitly. |
sensor AND temperature |
Require both terms. |
sensor AND NOT optical |
Require sensor and exclude optical. |
(sensor OR probe) AND temperature |
Require temperature and at least one of sensor or probe. |
"soil moisture" |
Search for the phrase in this order. |
Lowercase and, or, and not are search terms rather than Boolean operators. The
symbolic forms &&, ||, and ! are also supported; uppercase words are usually easier
to read. A quoted phrase in a text field does not require the entire field value to
equal that phrase.
Advanced search#
Use the filters on the search results page to narrow the results. The API provides equivalent facet parameters. The instrument filters configured for published records are:
| API parameter | Instrument field |
|---|---|
instrument_type |
metadata.InstrumentType.instrumentTypeName |
manufacturer |
metadata.Manufacturer.manufacturerName |
measured_variable |
metadata.MeasuredVariable |
owner |
metadata.Owner.ownerName |
Facet values must match the indexed values, including capitalisation. Use the response’s
aggregations to discover available values. For example:
curl --fail-with-body -sS --get 'https://b2inst-test.gwdg.de/api/records' \
--data-urlencode 'q=metadata.Name:sensor' \
--data-urlencode 'manufacturer=Stevens Water Monitoring Systems' \
--data-urlencode 'sort=newest'
Published-record searches also configure access_status, file_type, and the inherited
resource_types facet. Resource-type buckets may be empty for instrument records.
Use page and size for pagination; page numbers start at 1. Available sort values
are bestmatch, newest, oldest, version, mostviewed, and mostdownloaded.
The default is bestmatch with a query and newest without one. newest and oldest
sort by the record’s creation timestamp.
To restrict a search to a community, use
GET /api/communities/<community-id-or-slug>/records with the same q parameter.
See list records per community.
Field-specific searches#
Prefix a search value with its full field path and a colon. Instrument field names are
case-sensitive and start with metadata.. For example, metadata.Name:sensor searches
the instrument name, whereas sensor searches across the default searchable fields.
| Field | Search path | Matching type |
|---|---|---|
| Name | metadata.Name |
Text |
| Description | metadata.Description |
Text |
| Owner | metadata.Owner.ownerName |
Text |
| Manufacturer | metadata.Manufacturer.manufacturerName |
Text |
| Model | metadata.Model.modelName |
Text |
| Instrument type | metadata.InstrumentType.instrumentTypeName |
Text |
| Measured variable | metadata.MeasuredVariable |
Text |
| Landing page | metadata.LandingPage |
Keyword |
| Instrument identifier | metadata.Identifier.identifierValue |
Keyword |
| Alternative identifier | metadata.AlternateIdentifier.alternateIdentifierValue |
Keyword |
| Instrument date | metadata.Date.Date |
Date |
Manufacturer and Model are singular in the field paths. A record can list multiple
manufacturers, while Model is a single object. Legacy paths such as titles.title
and bare Name do not refer to the v3 instrument name field.
These queries illustrate phrase searches, combinations of fields, and grouped conditions:
metadata.Name:"soil moisture"
metadata.Owner.ownerName:"University of Rostock"
metadata.Manufacturer.manufacturerName:Stevens AND metadata.Name:sensor
metadata.Name:(sensor AND NOT optical)
For a whole-value match, the text fields in the table other than Description also
have a .keyword subfield. For example:
metadata.Manufacturer.manufacturerName.keyword:"Stevens Water Monitoring Systems"
Keyword matching preserves capitalisation. These .keyword subfields omit values
longer than 256 characters; use the text field for longer values. Quoting a value
also protects spaces and query punctuation, for example when searching for a Handle:
metadata.Identifier.identifierValue:"21.11157/example"
The Handle above is illustrative. Replace it with an identifier from a record.
Community-specific metadata field searches#
V3 stores community extension values under metadata.community_extension. The schema
identifier is stored separately in metadata.community_extension_schema; it is not
part of each field’s path. The old community_specific.<schema-uuid>.<field> query
format does not describe this structure.
Finding a community’s schema and field paths#
Request GET /api/community-schema-extension/<community-id-or-slug> to discover the
community’s latest extension schema. The response contains its uuid and a url for
the JSON Schema. A community without an extension schema returns 404.
GET /api/community-schema-extension/schema/<schema-uuid> returns the extension’s
backend, ui, facets, and search_map definitions. Inspect the record’s
metadata.community_extension keys and the full paths in search_map to construct a
field query. For an existing record, use its metadata.community_extension_schema
value to inspect the schema associated with that record, which may differ from the
community’s latest schema.
Searching for a community-specific metadata field value#
For example, the bundled Aalto schema defines a field named aalto:project_name.
If that schema is installed and records contain the field, its search path is
metadata.community_extension.aalto\:project_name. Escape the colon inside the field
name with a backslash so it is not confused with the colon separating the field and
the search value:
metadata.community_extension.aalto\:project_name:climate
The equivalent API request is:
curl --fail-with-body -sS --get 'https://b2inst-test.gwdg.de/api/records' \
--data-urlencode 'q=metadata.community_extension.aalto\:project_name:climate'
Use fields actually defined by the record’s schema. The example does not imply that
the Aalto schema or matching records are installed on the test service. To select a
particular schema, add AND metadata.community_extension_schema:"<schema-uuid>" to
the query, replacing the placeholder. To select records belonging to a particular
community, use the community records endpoint described above.
Searching with date ranges#
Range queries use TO between two bounds. A square bracket includes its bound; a
curly brace excludes it. * can be used for an open bound.
Filtering by creation or modification date#
| Field | Search path |
|---|---|
| Record creation timestamp | created |
| Record modification timestamp | updated |
Use created and updated, without a leading underscore. These are record timestamps,
distinct from dates supplied in instrument metadata.
Find records created during 2025:
created:[2025-01-01T00:00:00Z TO 2026-01-01T00:00:00Z}
Find records created in the first quarter of 2026:
created:[2026-01-01T00:00:00Z TO 2026-04-01T00:00:00Z}
Both queries include midnight at the start and exclude midnight at the end. The Z
specifies UTC. Explicit timestamps avoid ambiguity at date boundaries.
Find records modified on or after 1 September 2026:
updated:[2026-09-01T00:00:00Z TO *]
Chronological ranges require a field mapped as a date. Community extension fields are
mapped dynamically, with automatic date and numeric detection disabled. A community
field containing the string "2019" is therefore not automatically a date or a number;
confirm its index mapping before using chronological or numeric range queries.
Support#
For help with B2INST or comments on this guide, submit a request through the EUDAT support ticketing system.
Last update: 23.09.2026
Last review: 23.09.2026