Search in the delivery collection

Performs a search query by passing all query parameters to Solr.
Search results will contain unprotected and protected items. This route is restricted to authenticated users.
The supported query parser for the "defType" parameter can be "edismax" or "lucene". The query parser name defined in "q" or "fq" parameter through "{! ...}" can have the value "join", "lucene", "edismax", or "geofilt". For more information about the query syntax and the available query parameters, see the Solr documentation.

Description of the delivery collection schema

The table below lists the Name of each field from the delivery collection. Additionally, it contains a Description of each field along with the following information:

  • JSON Data Type: This column specifies the data type of field values that Watson Content Hub returns in the result of a query.
  • Solr Field Type: This column specifies how Watson Content Hub stores values of the field in the delivery collection.
    • boolean: This field type is based on the Solr BoolField class.
    • date: This field type is based on the Solr TrieDateField class.
    • int: This field type is based on the Solr TrieIntField class.
    • long: This field type is based on the Solr TrieLongField class.
    • location_rpt: This field type is based on the Solr LatLonPointSpatialField class.
    • path_hierarchical_index: This field type is based on the Solr TextField class. It uses a hierarchical path tokenizer to index field values.
    • string: This field type is based on the Solr StrField class.
    • string_ci: This field type is based on the Solr TextField class. It is a case insensitive version of string field type.
    • text_general: This field type is based on the Solr TextField class.
  • Indexed: This column specifies whether you can use values of the field in a query to retrieve matching documents.
  • Stored: This column specifies whether you can retrieve the actual value of the field using a query. The fields highlighted in this column are included in the query result by default. To override that default field list, use the "fl" parameter in your query.
NameDescriptionJSON Data TypeSolr Field TypeIndexedStored*
aggregatedIdsFor pages, this field contains the IDs that the page's appearance is made up of. This comprises the page's ID as well as the IDs of the page content item and it's directly referenced content items. Changes in one of those items will cause the page to be re-indexed.array of stringsstring_citruetrue
aggregatedContentIdsFor pages, this field contains the content IDs that the page's appearance is made up of. This comprises the IDs of the page content item and it's directly referenced content items. Changes in one of those items will cause the page to be re-indexed.array of stringsstring_citruetrue
assetTypeFor assets, this field contains the asset type. The value that is returned can be "document", "file", "image", or "video".stringstring_citruetrue
boolean1For content, this field can contain boolean element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.array of booleansbooleantruetrue
boolean2For content, this field can contain boolean element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.array of booleansbooleantruetrue
categoriesThe list of all category selections for the asset or content. All category selection elements on content are merged into this property.array of stringspath_hierarchical_indextruetrue
categoryLeavesThe list of all leaf category selection elements for the asset or content.array of stringsstring_citruefalse
classificationThis field describes the kind of item. The value that is returned can be "asset", "category", "content" or "taxonomy".stringstring_citruetrue
createdThe creation date of the item.stringdatetruetrue
creatorIdThe UUID of the user that created the item.stringstringtruetrue
date1For content, this field can contain date element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.array of stringsdatetruetrue
date2For content, this field can contain date element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.array of stringsdatetruetrue
descriptionThe description of the item.stringtext_generaltruetrue
documentFor assets and content, this field contains the full JSON document for the item.stringstringfalsetrue
fileSizeFor assets, this field contains the file size in bytes.numberlongtruetrue
generatedFilesFor content, this field contains the list of path values related to files that are generated by pre-rendering the item.array of stringsstringtruetrue
heightFor images, this field contains the height.numberinttruetrue
hideFromNavigationFor pages, this field specifies whether it should be hidden from navigation controls.booleanbooleantruetrue
idThe identifier of the item. For items of the same "classification", this identifier is unique. The combination of the "classification" and the "id" is unique across all items of the Watson Content Hub tenant.stringstringtruetrue
isManagedFor assets and content, this field specifies whether the content is managed or not managed and whether the asset is a managed asset or a so-called non-managed web asset.booleanbooleantruefalse
keywordsThe list of keywords related to the item.array of stringsstring_citruetrue
kindFor pages, this field contains all kinds a page is assigned to.array of stringsstring_citruetrue
lastModifiedThe last modification date of the item.stringdatetruetrue
lastModifierIdThe UUID of the user that last modified the item.stringstringtruetrue
localeThe language for which the item was created.stringstring_citruetrue
locationFor assets, this field contains the folder path without the file name. This allows for efficient queries for sibling assets.stringstring_citruefalse
location1For content, this field contains an array of strings. Each string consists of the latitude and the longitude of location elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.array of stringslocation_rpttruefalse
locationPathsFor assets, this field contains all of the path segments. This allows for efficient queries that return assets in subfolders of the queried value. For example, the query locationPaths:"/dxdam" will return assets that are stored in the /dxdam folder or any subfolder.stringpath_hierarchical_indextruefalse
locationsFor content, this field contains an array of strings. Each string consists of the latitude and the longitude of a Location element of the content item. For example, this field contains ["48.666259, 9.039273", "53.418880, -6.416081"] for a content item with two Location elements.array of stringslocation_rpttruetrue
mediaFor assets, this field contains the URL to the binary of the asset. It is relative to the API URL for your tenant.stringstring_citruetrue
mediaTypeFor assets, this field contains the media type.stringstringtruetrue
nameThe name of the item.stringstring_citruetrue
number1For content, this field can contain number element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.array of numbersdoubletruetrue
number2For content, this field can contain number element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.array of numbersdoubletruetrue
parentIdFor pages, this field contains the ID of the parent page.stringstring_citruetrue
pathFor assets, this field contains the folder path including file name.stringstring_citruetrue
positionFor pages, this field contains the position of the page relative to it's sibling pages.numberinttruetrue
resourceFor assets, this field contains the ID of the related resource. You can use this resource ID with the authoring and delivery resource service REST APIs.stringstringtruetrue
restrictedThis field specifies whether the item is restricted.booleanbooleantruefalse
siteIdFor pages, this field contains the ID of the site the page belongs to.stringstring_citruetrue
statusFor assets and content, this field contains the state the item is in. The value of this field can be "ready" or "retired".stringstring_citruetrue
string1For content, this field can contain string element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.array of stringsstring_citruetrue
string2For content, this field can contain string element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.array of stringsstring_citruetrue
string3For content, this field can contain string element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.array of stringsstring_citruetrue
string4For content, this field can contain string element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.array of stringsstring_citruetrue
sortableDate1For content, this field can contain a single date element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.stringdatetruetrue
sortableDate2For content, this field can contain a single date element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.stringdatetruetrue
sortableNumber1For content, this field can contain a single number element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.numberdoubletruetrue
sortableNumber2For content, this field can contain a single number element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.numberdoubletruetrue
sortableString1For content, this field can contain a single string element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.stringstring_citruetrue
sortableString2For content, this field can contain a single string element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.stringstring_citruetrue
sortableString3For content, this field can contain a single string element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.stringstring_citruetrue
sortableString4For content, this field can contain a single string element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item.stringstring_citruetrue
tagsThe list of tags assigned to the item.array of stringsstring_citruetrue
textFor content, this field is a collection of field names and text fragments that make up the item. It facilitates full-text search.array of stringstext_generaltruefalse
thumbnailFor assets, this field contains the URL to the thumbnail of the asset. It is relative to the API URL for your tenant.stringstring_citruetrue
typeFor content, this field contains the name of the content type.stringstring_citruetrue
typeIdFor content, this field contains the ID of the content type.stringstring_citruetrue
urlFor assets, this field contains the server relative URL to the binary document of the asset. For pages, it contains the URL under which the page can be adressed in an SPA.stringstringfalsetrue
widthFor images, this field contains the width.numberinttruetrue

* Note: Temporarily, the delivery collection might store field values even though the table above indicates otherwise.

Search Query Examples

Using a wildcard in the search term

In this example, the request URL defines a query using the standard query syntax. The "name" field is specified as the query field. The search term contains a wildcard to match any name that starts with the word "Red", for example "Red clover" or "Red_clover.pdf".
The "numFound" property from the response provides the number of documents that match the query. The value of the "documents" property contains the documents from the delivery collection selected by the query. Each document is returned with its stored fields as explained in the description of the delivery collection schema.

Request:
{baseURL}/mydelivery/v1/search?q=name:Red*
Response:
{
    "numFound": 4,
    "documents": [
        {
            "id": "53876d53-fbcf-45cf-8d53-f640c93f55c0",
            "name": "Red_clover.jpg",
            "classification": "asset",
            "description": "This is an image of a red clover plant.",
            "lastModified": "2017-06-27T14:49:12.160Z",
            "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
            "created": "2017-06-27T14:49:09.197Z",
            "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
            "tags": [
                "red clover",
                "clover",
                "alpine clover",
                "pink color",
                "plant",
                "purple color",
                "herb"
            ],
            "mediaType": "image/jpeg",
            "path": "/dxdam/53/53876d53-fbcf-45cf-8d53-f640c93f55c0/Red_clover.jpg",
            "fileSize": 25513,
            "assetType": "image",
            "resource": "b110f3efdb6e1d305a88348b1caca710",
            "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/53/53876d53-fbcf-45cf-8d53-f640c93f55c0/Red_clover.jpg"
        },
        {
            "id": "7001cf29-b28b-4462-9b4a-827ab15eaff4",
            "name": "Red_clover.pdf",
            "classification": "asset",
            "description": "Description of the red clover.",
            "lastModified": "2017-06-27T14:49:14.409Z",
            "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
            "created": "2017-06-27T14:49:13.130Z",
            "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
            "tags": [
                "Trifolium pratense",
                "US Department of Agriculture",
                "American Cancer Society",
                "Europe",
                "Clover",
                "Western Asia",
                "South America",
                "Africa"
            ],
            "mediaType": "application/pdf",
            "path": "/dxdam/70/7001cf29-b28b-4462-9b4a-827ab15eaff4/Red_clover.pdf",
            "fileSize": 331680,
            "assetType": "file",
            "resource": "14da685e6f1c2c67b26d5a0c80bc2be8",
            "keywords": [
                "red clover",
                "Trifolium pratense",
                "red clover flowers",
                "red clover rust",
                "Red Clover Pollination",
                "Red Clover Tea",
                "South America"
            ],
            "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/70/7001cf29-b28b-4462-9b4a-827ab15eaff4/Red_clover.pdf"
        },
        {
            "id": "454581ee-d0f1-4eb3-9ac6-3ce4990cce24",
            "name": "Red_clover_herbarium.jpg",
            "classification": "asset",
            "description": "This is an image of the red clover from an herbarium.",
            "lastModified": "2017-06-27T14:49:13.608Z",
            "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
            "created": "2017-06-27T14:49:11.157Z",
            "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
            "tags": [
                "olive green color",
                "plant",
                "clover",
                "herbarium",
                "sage green color"
            ],
            "mediaType": "image/jpeg",
            "path": "/dxdam/45/454581ee-d0f1-4eb3-9ac6-3ce4990cce24/Red_clover_herbarium.jpg",
            "fileSize": 557238,
            "assetType": "image",
            "resource": "e7cd2cac2e5bfce2878a707377bf42d6",
            "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/45/454581ee-d0f1-4eb3-9ac6-3ce4990cce24/Red_clover_herbarium.jpg"
        },
        {
            "id": "c65a949c-5822-49bb-ad5d-647cd9820c57",
            "name": "Red clover",
            "classification": "content",
            "description": "This content provides information on the red clover.",
            "lastModified": "2017-06-27T14:49:36.389Z",
            "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
            "created": "2017-06-27T14:49:36.389Z",
            "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
            "tags": [
                "clover",
                "purple",
                "luck",
                "pink"
            ],
            "type": "Plant",
            "categories": [
                "Plant classification/Plantae/Angiosperms/Eudicots/Rosids/Fabales/Fabaceae/Faboideae/Trifolieae/Trifolium",
                "Plant habitats/Grassland/Meadow/Wet meadow"
            ]
        }
    ]
}

Specifying the fields to return

This example demonstrates the use of the "fl" parameter. It defines that only the "name" field and the "classification" field will be returned for each document matching the query.
The number of returned documents is limited to 10 by default.

Request:
  {baseURL}/mydelivery/v1/search?q=tags:thistle&fl=name&fl=classification
Response:
{
    "numFound": 12,
    "documents": [
        {
            "name": "Spiny_sowthistle.jpg",
            "classification": "asset"
        },
        {
            "name": "Common_sowthistle_herbarium.jpg",
            "classification": "asset"
        },
        {
            "name": "Common_sowthistle.pdf",
            "classification": "asset"
        },
        {
            "name": "Common_sowthistle.jpg",
            "classification": "asset"
        },
        {
            "name": "Spiny_sowthistle_herbarium.jpg",
            "classification": "asset"
        },
        {
            "name": "Spiny_sowthistle.pdf",
            "classification": "asset"
        },
        {
            "name": "Common sowthistle",
            "classification": "content"
        },
        {
            "name": "Spiny sowthistle",
            "classification": "content"
        },
        {
            "name": "Marsh thistle",
            "classification": "content"
        },
        {
            "name": "Marsh_thistle.jpg",
            "classification": "asset"
        }
    ]
}

Limiting the number of results and returned fields

In this example, the maximum number of documents to include in the query result is limited to 5.
By default, if you do not specify the "rows" parameter, the service returns a maximum of 10 documents.
The "fl" parameter defines that only the "name" field and the "classification" field will be returned for each document matching the quey.

Request:
  {baseURL}/mydelivery/v1/search?q=tags:thistle&fl=name&fl=classification&rows=5
Response:
{
    "numFound": 12,
    "documents": [
        {
            "name": "Spiny_sowthistle.jpg",
            "classification": "asset"
        },
        {
            "name": "Common_sowthistle_herbarium.jpg",
            "classification": "asset"
        },
        {
            "name": "Common_sowthistle.pdf",
            "classification": "asset"
        },
        {
            "name": "Common_sowthistle.jpg",
            "classification": "asset"
        },
        {
            "name": "Spiny_sowthistle_herbarium.jpg",
            "classification": "asset"
        }
    ]
}

Paging through the query result

In this example, the "rows" parameter is still set to 5 to limit the number of documents returned by the query. The "start" parameter defines an offset of 3. Therefore, the result of the query includes documents 4 through 8 from a total of 12 documents that match the query. The default value of the "start" parameter is 0.

Request:
  {baseURL}/mydelivery/v1/search?q=tags:thistle&fl=name&fl=classification&rows=5&start=3
Response:
{
    "numFound": 12,
    "documents": [
        {
            "name": "Common_sowthistle.pdf",
            "classification": "asset"
        },
        {
            "name": "Spiny_sowthistle_herbarium.jpg",
            "classification": "asset"
        },
        {
            "name": "Spiny_sowthistle.pdf",
            "classification": "asset"
        },
        {
            "name": "Common sowthistle",
            "classification": "content"
        },
        {
            "name": "Spiny sowthistle",
            "classification": "content"
        }
    ]
}

Sorting the query result

In this example, the query contains the "sort" parameter to sort the query result by "name" and "lastModified" in an ascending order. The response includes the first 5 documents from the sorted query result.

Request:
  {baseURL}/mydelivery/v1/search?q=tags:thistle&fl=name&fl=classification&rows=5&sort=name asc, lastModified asc
Response:
{
    "numFound": 12,
    "documents": [
        {
            "name": "Common sowthistle",
            "classification": "content"
        },
        {
            "name": "Common_sowthistle.jpg",
            "classification": "asset"
        },
        {
            "name": "Common_sowthistle.pdf",
            "classification": "asset"
        },
        {
            "name": "Common_sowthistle_herbarium.jpg",
            "classification": "asset"
        },
        {
            "name": "Marsh thistle",
            "classification": "content"
        }
    ]
}

Getting only the number of matching documents

This example demonstrates how you can limit the response to only the number of documents that match the query by adding the "rows" parameters with a value of 0.

Request:
  {baseURL}/mydelivery/v1/search?q=*:*&rows=0
Response:
{
    "numFound": 182
}

Using boolean operators in a query

This example demonstrates the use of a boolean operator to combine different conditions in the query. This particular query returns Watson Content Hub "content" that is tagged with "dandelion". The fields of matching documents that are included in the response are limited to "name", "classification", and "tags".

Request:
  {baseURL}/mydelivery/v1/search?q=classification:content AND tags:dandelion&fl=name&fl=classification&fl=tags
Response:
{
    "numFound": 1,
    "documents": [
        {
            "name": "Common dandelion",
            "classification": "content",
            "tags": [
                "dandelion",
                "yellow",
                "tortoise"
            ]
        }
    ]
}

Getting the "document" field as JSON object

In this example, the query is extended by an additional "fl" parameter to also retrieve the "document" field. To return the value of that specific field as JSON object, the "[json]" qualifier is added. By default, the field value is returned as an escaped JSON string.

Request:
  {baseURL}/mydelivery/v1/search?q=classification:content AND tags:dandelion&fl=name&fl=classification&fl=tags&fl=document:[json]
Response:
{
    "numFound": 1,
    "documents": [
        {
            "name": "Common dandelion",
            "classification": "content",
            "tags": [
                "dandelion",
                "yellow",
                "tortoise"
            ],
            "document": {
                "id": "662c212c-e8f6-4dcc-b4fa-cddb76aac7c0",
                "name": "Common dandelion",
                "description": "This content provides information on the common dandelion.",
                "classification": "content",
                "typeId": "357e5d59-be20-4fe5-ba9e-31913f6fc229",
                "locale": "en",
                "lastModified": "2017-06-27T14:49:35.361Z",
                "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
                "created": "2017-06-27T14:49:35.361Z",
                "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
                "tags": [
                    "dandelion",
                    "yellow",
                    "tortoise"
                ],
                "status": "ready",
                "elements": {
                    "source": {
                        "elementType": "link",
                        "linkURL": "https://en.wikipedia.org/wiki/Taraxacum_officinale",
                        "linkText": "Wikipedia"
                    },
                    "scientificClassification": {
                        "elementType": "category",
                        "categoryIds": [
                            "e7411413986ff741cb4495df45e4b7a1"
                        ],
                        "categories": [
                            "Plant classification/Plantae/Angiosperms/Eudicots/Asterids/Asterales/Asteraceae/Cichorioideae/Cichorieae/Taraxacum"
                        ]
                    },
                    "attachment": {
                        "elementType": "file",
                        "asset": {
                            "id": "ba56e2b8-c7bf-4f45-b791-323f85fdfbc5",
                            "resourceUri": "/delivery/v1/resources/623912367a4183a13fd53be2ad9d65e9",
                            "fileSize": 485686,
                            "fileName": "Common_dandelion.pdf",
                            "mediaType": "application/pdf"
                        },
                        "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/ba/ba56e2b8-c7bf-4f45-b791-323f85fdfbc5/Common_dandelion.pdf"
                    },
                    "commonNames": {
                        "elementType": "text",
                        "value": "common dandelion,dandelion"
                    },
                    "binomialName": {
                        "elementType": "text",
                        "value": "taraxacum officinale"
                    },
                    "herbariumSpecimenDate": {
                        "elementType": "datetime",
                        "value": "1999-10-02T22:00:00Z"
                    },
                    "photo": {
                        "elementType": "image",
                        "renditions": {
                            "default": {
                                "renditionId": "1d9c8fd6-5d82-477c-bf5c-08ef8bd3f9c8",
                                "source": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91",
                                "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg"
                            }
                        },
                        "asset": {
                            "id": "16ae839a-5c79-4d83-bc80-14fa794c890f",
                            "resourceUri": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91",
                            "fileName": "Common_dandelion.jpg",
                            "fileSize": 24800,
                            "mediaType": "image/jpeg"
                        },
                        "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg"
                    },
                    "description": {
                        "elementType": "text",
                        "value": "Taraxacum officinale is a flowering herbaceous perennial plant of the family Asteraceae (Compositae).\n\nIt can be found growing in temperate regions of the world, in lawns, on roadsides, on disturbed banks and shores of water ways, and other areas with moist soils. T. officinale is considered a weed, especially in lawns and along roadsides, but it is sometimes used as a medical herb and in food preparation. Common dandelion is well known for its yellow flower heads that turn into round balls of silver tufted fruits that disperse in the wind called \"blowballs\" or \"clocks\" (in both British and American English).\n\nTaraxacum officinale grows from generally unbranched taproots and produces one to more than ten stems that are typically 5–40 cm (2.0–15.7 in) tall, but sometimes up to 70 cm (28 in) tall. The stems can be tinted purplish, they are upright or lax, and produce flower heads that are held as tall or taller than the foliage. The foliage may be upright-growing or horizontally spreading; the leaves have petioles that are either unwinged or narrowly winged. The stems can be glabrous or sparsely covered with short hairs. Plants have milky latex and the leaves are all basal; each flowering stem lacks bracts and has one single flower head. The yellow flower heads lack receptacle bracts and all the flowers, which are called florets, are ligulate and bisexual. In many lineages, fruits are mostly produced by apomixis, notwithstanding the flowers are visited by many types of insects.\n\nThe leaves are 5–45 cm (2.0–17.7 in) long and 1–10 cm (0.39–3.94 in) wide, and are oblanceolate, oblong, or obovate in shape, with the bases gradually narrowing to the petiole. The leaf margins are typically shallowly lobed to deeply lobed and often lacerate or toothed with sharp or dull teeth.\n\nThe calyculi (the cuplike bracts that hold the florets) are composed of 12 to 18 segments: each segment is reflexed and sometimes glaucous. The lanceolate shaped bractlets are in two series, with the apices acuminate in shape. The 14–25 mm (0.55–0.98 in) wide involucres are green to dark green or brownish-green, with the tips dark gray or purplish. The florets number 40 to over 100 per head, having corollas that are yellow or orange-yellow in color.\n\nThe fruits, called cypselae, range in color from olive-green or olive-brown to straw-colored to grayish, they are oblanceoloid in shape and 2–3 mm (0.079–0.118 in) long with slender beaks. The fruits have 4 to 12 ribs that have sharp edges. The silky pappi, which form the parachutes, are white to silver-white in color and around 6 mm wide. Plants typically have 24 or 40 pairs of chromosomes, while some have 16 or 32 pairs."
                    },
                    "herbariumSpecimenLocality": {
                        "elementType": "category",
                        "categoryIds": [
                            "e7cd2cac2e5bfce2878a7073777b0e78"
                        ],
                        "categories": [
                            "Plant habitats/Grassland/Meadow/Wet meadow"
                        ]
                    },
                    "herbariumSpecimenPhoto": {
                        "elementType": "image",
                        "renditions": {
                            "default": {
                                "renditionId": "2be697cd-30df-4f1d-afc8-ac17fa0ab5a0",
                                "source": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530",
                                "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg"
                            },
                            "medium": {
                                "renditionId": "eb688f20-2fb0-414f-a6aa-8f6e0f8a61b3",
                                "source": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530?resize=800px:1100px&crop=800:1100;0,0",
                                "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg?resize=800px%3A1100px&crop=800%3A1100%3B0%2C0"
                            },
                            "large": {
                                "renditionId": "112f0a63-72b0-4b39-b769-c7bdadcae542",
                                "source": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530?resize=1200px:1650px&crop=1200:1650;0,0",
                                "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg?resize=1200px%3A1650px&crop=1200%3A1650%3B0%2C0"
                            },
                            "small": {
                                "renditionId": "4a06a904-64cd-4942-ae1b-1b15389e48e2",
                                "source": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530?resize=400px:550px&crop=400:550;0,0",
                                "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg?resize=400px%3A550px&crop=400%3A550%3B0%2C0"
                            }
                        },
                        "asset": {
                            "id": "852c1de4-661e-4a18-9ba8-bb49c65c50a6",
                            "resourceUri": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530",
                            "fileName": "Common_dandelion_herbarium.jpg",
                            "fileSize": 695051,
                            "mediaType": "image/jpeg"
                        },
                        "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg"
                    }
                },
                "type": "Plant"
            }
        }
    ]
}

Getting documents including all available stored fields

In this example, the query matches all Watson Content Hub items of type "asset" that are tagged with "dandelion". The response includes the first document matching the query and provides all stored fields that are available for that document.

Request:
  {baseURL}/mydelivery/v1/search?q=classification:asset AND tags:dandelion&fl=*&rows=1&fl=document:[json]
Response:
{
    "numFound": 3,
    "documents": [
        {
            "id": "16ae839a-5c79-4d83-bc80-14fa794c890f",
            "name": "Common_dandelion.jpg",
            "classification": "asset",
            "description": "This is an image of a common dandelion plant.",
            "lastModified": "2017-06-27T14:49:20.045Z",
            "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
            "created": "2017-06-27T14:49:18.152Z",
            "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
            "tags": [
                "hawkweed",
                "common dandelion",
                "pale yellow color",
                "oxtongue",
                "dandelion",
                "cat's-ear",
                "plant",
                "weed",
                "yellow color",
                "herb"
            ],
            "mediaType": "image/jpeg",
            "path": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg",
            "fileSize": 24800,
            "location": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f",
            "locationPaths": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f",
            "assetType": "image",
            "resource": "14da685e6f1c2c67b26d5a0c80b2ed91",
            "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg",
            "height": 300,
            "width": 300,
            "document": {
                "mediaType": "image/jpeg",
                "name": "Common_dandelion.jpg",
                "path": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg",
                "digest": "JK500obHI3/Rq9eoL+6/mg==",
                "usageRights": {
                    "categories": []
                },
                "assetType": "image",
                "lastModified": "2017-06-27T14:49:20.045Z",
                "description": "This is an image of a common dandelion plant.",
                "tags": {
                    "values": [
                        "classification:hawkweed",
                        "classification:common dandelion",
                        "classification:pale yellow color",
                        "classification:oxtongue",
                        "dandelion",
                        "classification:cat's-ear",
                        "classification:plant",
                        "classification:weed",
                        "classification:yellow color",
                        "classification:herb"
                    ],
                    "declined": [],
                    "analysis": "complete",
                    "suggested": [
                        "classification:common dandelion",
                        "classification:herb",
                        "classification:plant",
                        "classification:cat's-ear",
                        "classification:weed",
                        "classification:hawkweed",
                        "classification:pale yellow color"
                    ]
                },
                "altText": "common dandelion",
                "categoryIds": [],
                "fileName": "Common_dandelion.jpg",
                "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
                "cognitive": {
                    "classifications": [
                        "common dandelion",
                        "herb",
                        "plant",
                        "cat's-ear",
                        "weed",
                        "hawkweed",
                        "pale yellow color"
                    ],
                    "faces": [],
                    "colors": {
                        "vibrant": "#d5b706",
                        "muted": "#5c4c44",
                        "darkVibrant": "#856706",
                        "darkMuted": "#46522b"
                    },
                    "status": "complete"
                },
                "id": "16ae839a-5c79-4d83-bc80-14fa794c890f",
                "resource": "14da685e6f1c2c67b26d5a0c80b2ed91",
                "fileSize": 24800,
                "status": "ready",
                "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
                "renditions": {
                    "default": {
                        "id": "r=14da685e6f1c2c67b26d5a0c80b2ed91&a=16ae839a-5c79-4d83-bc80-14fa794c890f",
                        "source": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91"
                    }
                },
                "metadata": {
                    "width": 300,
                    "height": 300
                },
                "classification": "asset",
                "created": "2017-06-27T14:49:18.152Z",
                "links": {
                    "media": {
                        "href": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91.jpg"
                    },
                    "thumbnail": {
                        "href": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91?fit=inside%7C220:145"
                    }
                },
                "categories": []
            },
            "media": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91.jpg",
            "thumbnail": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91?fit=inside%7C220:145",
            "isManaged": true,
            "status": "ready",
        }
    ]
}

Searching only in a subset of all documents

This example demonstrates the use of the "fq" parameter to search only in the specific subset of all documents that are classified as "asset". The filter query is a means to limit the set of documents that can be returned by a query. Restricting the query to a subset of all documents can speed up complex queries, because the filter query is cached independently from the main query.

Request:
  {baseURL}/mydelivery/v1/search?fq=classification:asset&q=tags:dandelion&fl=name&fl=classification
Response:
{
    "numFound": 3,
    "documents": [
        {
            "name": "Common_dandelion.pdf",
            "classification": "asset"
        },
        {
            "name": "Common_dandelion_herbarium.jpg",
            "classification": "asset"
        },
        {
            "name": "Common_dandelion.jpg",
            "classification": "asset"
        }
    ]
}

Getting documents based on the last modification date

This example demonstrates the use of the "fq" parameter to search only in the specific subset of all documents that were modified in the last 2 days. The filter query is a means to limit the set of documents that can be returned by a query. Restricting the query to a subset of all documents can speed up complex queries, because the filter query is cached independently from the main query.

Request:
  {baseURL}/mydelivery/v1/search?fq=lastModified:[NOW-2DAYS/DAY TO NOW]&q=tags:thistle&fl=lastModified&fl=name
Response:
{
    "numFound": 4,
    "documents": [
        {
            "name": "Marsh thistle",
            "lastModified": "2017-07-03T08:37:10.966Z"
        },
        {
            "name": "Marsh_thistle.jpg",
            "lastModified": "2017-07-03T08:38:50.870Z"
        },
        {
            "name": "Marsh_thistle_herbarium.jpg",
            "lastModified": "2017-07-03T08:39:29.610Z"
        },
        {
            "name": "Marsh_thistle.pdf",
            "lastModified": "2017-07-03T08:40:15.777Z"
        }
    ]
}

Getting documents with a specific field not set

In this example, all documents are filtered to retrieve only entries that have no data set for the field 'tags'. The query returns only the 5 most recently updated documents.

Request:
  {baseURL}/mydelivery/v1/search?q=*:*&fq=NOT tags:[* TO *]&sort=lastModified desc&rows=5&fl=name&fl=classification&fl=lastModified
Response:
{
    "numFound": 114,
    "documents": [
        {
            "name": "Chelidonium",
            "classification": "category",
            "lastModified": "2017-06-27T15:00:24.342Z"
        },
        {
            "name": "Taraxacum",
            "classification": "category",
            "lastModified": "2017-06-27T14:49:03.920Z"
        },
        {
            "name": "Trifolium",
            "classification": "category",
            "lastModified": "2017-06-27T14:49:02.458Z"
        },
        {
            "name": "Cirsium",
            "classification": "category",
            "lastModified": "2017-06-27T14:49:00.952Z"
        },
        {
            "name": "Achillea",
            "classification": "category",
            "lastModified": "2017-06-27T14:48:59.416Z"
        }
    ]
} 

Getting documents with a specific field not set in combination with an OR clause

In this example, all documents are filtered to retrieve only entries that were modified during the last 21 days or that have no data set for the field 'tags'. The query returns only the 5 most recently updated documents.

Request:
  {baseURL}/mydelivery/v1/search?q=*:*&fq=lastModified:[NOW-21DAYS TO NOW] OR (*:* NOT tags:[* TO *])&sort=lastModified desc&rows=5&fl=name&fl=classification&fl=lastModified
Response:
{
    "numFound": 115,
    "documents": [
        {
            "name": "Marsh thistle",
            "classification": "content",
            "lastModified": "2017-07-03T08:37:10.966Z"
        },
        {
            "name": "Chelidonium",
            "classification": "category",
            "lastModified": "2017-06-27T15:00:24.342Z"
        },
        {
            "name": "Taraxacum",
            "classification": "category",
            "lastModified": "2017-06-27T14:49:03.920Z"
        },
        {
            "name": "Trifolium",
            "classification": "category",
            "lastModified": "2017-06-27T14:49:02.458Z"
        },
        {
            "name": "Cirsium",
            "classification": "category",
            "lastModified": "2017-06-27T14:49:00.952Z"
        }
    ]
} 

Getting available facet terms

Faceted search organizes search results into categories based on terms from the indexed items. This can be useful, for example, to implement typeahead suggestions or filter functions.

To enable faceting, add the "facet" parameter to the request and set its value to "true". Then use the "facet.field" parameter to specify each field to be treated as a facet.
In this example, the response contains the facet terms that are available in the delivery collection for the fields "classification", "type", and "assetType".
The request does not contain a query that matches any documents. Therefore, the "numFound" property from the response and the number following each facet term are 0.

Request:
  {baseURL}/mydelivery/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType
Response:
{
    "numFound": 0,
    "facets": {
        "classification": [
            "asset",
            0,
            "category",
            0,
            "content",
            0,
            "taxonomy",
            0
        ],
        "type": [
            "plant",
            0
        ],
        "assetType": [
            "file",
            0,
            "image",
            0
        ]
    }
}

Getting available facet terms that contain a specific substring

This example demonstrates the use of the "facet.contains" parameter to retrieve only facet terms that contain a specific character or character sequence.

Request:
  {baseURL}/mydelivery/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType&facet.contains=nt
Response:
{
    "numFound": 0,
    "facets": {
        "classification": [
            "content",
            0
        ],
        "type": [
            "plant",
            0
        ],
        "assetType": []
    }
}

Limiting the number of returned facet terms

This example uses the "facet.limit" parameter to obtain only the first facet term for each selected facet.

Request:
  {baseURL}/mydelivery/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType&facet.limit=1
Response:
{
    "numFound": 0,
    "facets": {
        "classification": [
            "asset",
            0
        ],
        "type": [
            "plant",
            0
        ],
        "assetType": [
            "file",
            0
        ]
    }
}

Paging through the returned facet terms

In this example, the "facet.limit" parameter is still set to 1 to limit the number of facet terms in the response. The "facet.offset" parameter defines an offset of 1.
Therefore, the response includes the second facet term for each facet provided there are more facet terms available.

Request:
  {baseURL}/mydelivery/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType&facet.limit=1&facet.offset=1
Response:
{
    "numFound": 0,
    "facets": {
        "classification": [
            "category",
            0
        ],
        "type": [],
        "assetType": [
            "image",
            0
        ]
    }
}

Getting facet ranges

This example demonstrates the use of range faceting by adding corresponding "facet.range" parameters to the request.
Range faceting is supported on date and numeric fields that support range queries.

Request:
  {baseURL}/mydelivery/v1/search?facet=true&facet.range=created&facet.range.start=NOW/DAY-3DAYS&facet.range.end=NOW&facet.range.gap=%2B1DAY
Response:
{
    "numFound": 0,
    "facet_ranges": {
        "created": {
            "counts": [
                "2017-07-03T00:00:00Z",
                0,
                "2017-07-04T00:00:00Z",
                0,
                "2017-07-05T00:00:00Z",
                0,
                "2017-07-06T00:00:00Z",
                0
            ],
            "gap": "+1DAY",
            "start": "2017-07-03T00:00:00Z",
            "end": "2017-07-07T00:00:00Z"
        }
    }
}

Getting the facet term information for a query result

This example shows the combination of a query and faceting. The response contains information about the usage of the selected facet terms across all documents of the query result.
Among the 32 documents that match the query there are:

  • 24 documents with the "classification" field value set to "asset" and 8 classified as "content"
  • 8 documents with the content "type" field value set to "plant"
  • 16 documents with the "assetType" field value set to "image" and 8 assets of type "file"
Request:
  {baseURL}/mydelivery/v1/search?q=name:Common*&fl=name&fl=classification&facet=true&facet.field=classification&facet.field=type&facet.field=assetType&rows=5
Response:
{
    "numFound": 32,
    "documents": [
        {
            "name": "Common_daisy.jpg",
            "classification": "asset"
        },
        {
            "name": "Common_reed_herbarium.jpg",
            "classification": "asset"
        },
        {
            "name": "Common_yarrow.jpg",
            "classification": "asset"
        },
        {
            "name": "Common_buttercup_herbarium.jpg",
            "classification": "asset"
        },
        {
            "name": "Common_nettle.pdf",
            "classification": "asset"
        }
    ],
    "facets": {
        "classification": [
            "asset",
            24,
            "content",
            8,
            "category",
            0,
            "taxonomy",
            0
        ],
        "type": [
            "plant",
            8
        ],
        "assetType": [
            "image",
            16,
            "file",
            8
        ]
    }
}

Using the Extended DisMax query parser

The Watson Content Hub delivery search service REST API includes an additional query parser that supports more parameters than the standard query parser used in the previous examples.

In this example, the "defType" parameter tells the service to use the "edismax" query parser. The query that matches the term "content" or "asset" is performed on the query field "classification" that is specified using the "qf" parameter.
The response includes a maximum of 1 document as per "rows" parameter.

Request:
  {baseURL}/mydelivery/v1/search?q=content OR asset&defType=edismax&qf=classification&rows=1
Response:
{
    "numFound": 68,
    "documents": [
        {
            "id": "5a5f65c0-c01f-438e-acf1-a707cb3a9bed",
            "name": "Common nettle",
            "classification": "content",
            "description": "This content provides information on the common nettle.",
            "lastModified": "2017-06-27T14:49:35.370Z",
            "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
            "created": "2017-06-27T14:49:35.370Z",
            "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc",
            "tags": [
                "nettle",
                "brown",
                "green"
            ],
            "type": "Plant",
            "categories": [
                "Plant habitats/Grassland/Meadow/Wet meadow",
                "Plant classification/Plantae/Angiosperms/Eudicots/Rosids/Rosales/Urticaceae/Urticoideae/Urticeae/Urtica"
            ]
        }
    ]
}


User roles: admin, manager, editor, viewer, authenticatedVisitor

Language
Click Try It! to start a request and see the response here!