News and updates

  • 2020-11-11: Updated
  • 2019-07-18: Initial version

General

  • All parameter names are case sensitive. Parameter values are not case sensitive.
  • Search supports application/json media type only.

Introduction UPDATED

CDISC Library maintains an index. Index is a collection of multiple document types. A document type is comprised of related metadata, or fields. Certain fields are pre-aggregated with a list of unique values to aid filtering or subsetting. The search API performs searches against this index. This strategy allows searches to be completed very efficiently, with most requests in less than 500 ms.

Note, CDISC Library uses Microsoft Cognitive Search as the search engine as of the 2020-11-11 release. Technical explanations such as query expressions, filters, and syntax alike can be found in the Technical References section below.

Technical References NEW

Basic Construct

The basic construct of a search API request is /mdr/search?q={searchExpression}&{scope}={scopeExpression} , where:

ParameterDescriptionCardinality
q={searchExpression} Search expression to use in the query.1
{scope}={scopeEexpression}

The search scope and expression to filter against.

0..*

Response

This section summarizes how the API would respond for each scenario listed.

ScenarioStatus codeRemarks
Valid query with no matches200 Ok

UPDATED The API returns a response, in JSON format as follows:

{
    "hasMore": false,
    "hits": [],
    "totalHits": 0
}
Valid query with at least one match200 OkThe API returns a result set in JSON format. Each instance of matches will be in the hits element. The number of matches will appear in the totalHits element. Paging is supported.
Invalid query400 Bad Request

This includes, but not limited to, missing required parameter, malformed URL, and invalid paging. User should review the message and detail returned in the JSON-formatted response.

Search Expression UPDATED

A search expression {searchExpression} is a series of of terms and operators. It may be one of the following:

Expression typeExampleRemarks
Single termq=treatmentReturn entries from index where the term treatment appears.
Multiple termsq=date exposure treatmentReturn entries from index where all the terms date exposure treatment appear in one document, regardless of word order.

Refer to the the Technical References section for detailed explanations and examples.

Scopes

In general, scopes are pre-aggregated field terms for filtering or subsetting searches. An endpoint is available to obtain a list of scopes:

/mdr/search/scopes

Further, to obtain a list of pre-aggregated terms for each scope:

/mdr/search/scopes/{scope}

Example

Below is a sample response from /mdr/search/scopes/core, where core is one of the scopes, referring to the Core column in dataset specification tables in CDASH, SDTM, and ADaM products:

{
    "hasMore": false,
    "total": 7,
    "values": [
        "Conditionally Required",
        "Expected",
        "Highly Recommended",
        "Optional",
        "Permissible",
        "Recommended/Conditional",
        "Required"
    ]
}

Scope Expression UPDATED

A scope expression {scopeExpression} is a series of of terms and operators. It may be one of the following:

Expression typeExampleRemarks
Single termq={searchExpression}&core=Recommended
Limit the search to entries in the index where core contains the term Recommended.
Multiple terms q={searchExpression}&core=Conditionally%20Required

Limit the search to entries in the index where core contains the terms Conditionally Required.

Refer to the the Technical References section for detailed explanations and examples.

Match Highlighting UPDATED

Highlighting is disabled by default.

It is possible to have highlights added to indicate what part of the index matched the search. The highlights appear as pairs in the JSON-formatted response returned. Client applications can consume and render additional visualization.

ParameterDescriptionCardinality
highlight={fieldList} || *

A list of fields to highlight where matches are found. To enable highlighting, set the value of highlight to a comma-separated list of field names that should have highlighting applied. To highlight all fields, use * as the field name. The API will insert an element to each match instance, name highlight.

1

Refer to the the Technical References section for detailed explanations and examples.

Result Set Paging

Additional query parameters are available for paging. Paging is useful to limit and control the result set (or, hits) returned. By default, the API returns the first 100 hits. The total number of hits is at the end of a response.

ParameterDescriptionCardinality
start={startIndex} The initial result index to return, starting at 0. The default for {startIndex} is 0.0..1
pageSize={pageSize} The number of results to return, starting at {startIndex} . The default for {pageSize} is 100.0..1

Paging works for both searches and scope listings, as follows:

ApplicationAPI constructRemarks
Searches /mdr/search?q={searchExpression}&{scope}={scopeEexpression}&start={startIndex}&pageSize={pageSize} The total number of hits appears at the end of the API response, regardless of page index
Scope listings /mdr/search/scopes/{scope}&start={startIndex}&pageSize={pageSize}

Example

Listing SDTMIG v3.3 variables whose core is Required, returns the 51st to 100th matches, out of 344 hits in total:

q=&start=50&pageSize=50&product=SDTMIG%20v3.3&core=Required

« HTTP Status Codes

Diff »

  • No labels