api.v2.search

Help

Copyright ©

Mindbreeze GmbH, A-4020 Linz, 2017.

All rights reserved. All hardware and software names are brand names and/or trademarks of their respective manufacturers.

These documents are strictly confidential. The submission and presentation of these documents does not confer any rights to our software, our services and service outcomes or other protected rights.

The dissemination, publication or reproduction hereof is prohibited.

For ease of readability, gender differentiation has been waived. Corresponding terms and definitions apply within the meaning and intent of the equal treatment principle for both sexes.

OverviewPermanent link for this heading

Mindbreeze InSpire provides search results with a simple interface. This interface is based on HTTP and JSON. The full range of search possibilities are available.

Search requests are sent as HTTP POST to a client service. The path for search queries is:

<Client Service URL>/api/v2/search

A search for mindbreeze and five results provides results with the metadata title and content:

{

  "query": {

    "unparsed": "mindbreeze"

  },

  "count": 5,

  "properties": [{

    "name": "title",

    "formats": ["HTML"]

  },{

    "name": "content",

    "formats": ["HTML"]

  }]

}

Sample query with the command line tool curl:

curl https://demo.mindbreeze.com/public/api/v2/search -d '{"query": {"unparsed": "mindbreeze"}, "count":5, "properties": [{ "name": "title", "formats": ["HTML"]  },{ "name": "content", "formats": ["HTML"] }] }'

Sample Response

{

  "search_request": {

    "query": {

      "unparsed": "mindbreeze"

    },

    "count": 5,

    "properties": [

      {

        "name": "title",

        "formats": [

          "HTML"

        ]

      },

      {

        "name": "content",

        "formats": [

          "HTML"

        ]

      }

    ],

    "user_context": {}

  },

  "alternatives": [

    {

      "id": "user_query",

      "name": "user_query",

      "entries": [

        {

          "html": "mindbreeze",

          "count": 1,

          "query_expr": {

            "unparsed": "mindbreeze"

          }

        }

      ]

    }

  ],

  "name": "unnamed",

  "estimated_count": 676,

  "facets": [

    {

      "id": "mes:date",

      "name": "Date",

      "entries": [

        {

          "html": "2016",

          "count": 676,

          "query_expr": {

            "label": "mes:date",

            "and": [

              {

                "num": 1451606400000,

                "cmp": "GE",

                "unit": "ms_since_1970"

              },

              {

                "num": 1483228799999,

                "cmp": "LE",

                "unit": "ms_since_1970"

              }

            ],

            "description": "2016",

            "id": "2016",

            "value": {

              "num": 1451606400000,

              "unit": "ms_since_1970"

            }

          },

          "entries": [

            {

              "html": "July",

              "count": 676,

              "query_expr": {

                "label": "mes:date",

                "and": [

                  {

                    "num": 1467331200000,

                    "cmp": "GE",

                    "unit": "ms_since_1970"

                  },

                  {

                    "num": 1470009599999,

                    "cmp": "LE",

                    "unit": "ms_since_1970"

                  }

                ],

                "description": "July",

                "id": "2016.July",

                "value": {

                  "num": 1467331200000,

                  "unit": "ms_since_1970"

                }

              },

              "value": {

                "num": 1467331200000,

                "unit": "ms_since_1970"

              }

            }

          ],

          "value": {

            "num": 1451606400000,

            "unit": "ms_since_1970"

          },

          "order_criteria": "COUNT",

          "order_direction": "DESCENDING"

        }

      ],

      "order_criteria": "COUNT",

      "order_direction": "DESCENDING"

    }

  ],

  "orderby": "mes:relevance",

  "orderable": [

    {

      "name": "mes:relevance",

      "localized_name": "Relevance"

    },

    {

      "name": "mes:date",

      "localized_name": "Date"

    },

    {

    …

  ],

  "available_properties": [

    {

      "name": "Content-Type",

      "localized_name": "Content-Type"

    },

    {

      "name": "HandheldFriendly",

      "localized_name": "HandheldFriendly"

    },

    

  ],

  "available_facets": [

    {

      "name": "categoryclass",

      "localized_name": "Type"

    },

    {

      "name": "datasource/category",

      "localized_name": "datasource/category"

    },

    

  ],

  "resultset": {

    "results": [

      {

        "id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/de/vertragsmanagement.html:",

        "location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjcxNg==",

        "rank_score": 53.4155,

        "relevance_score": 53.4155,

        "properties": [

          {

            "id": "title",

            "name": "Title",

            "data": [

              {

                "html": "Vertragsmanagement | <em>Mindbreeze</em>"

              }

            ]

          },

          {

            "id": "content",

            "name": "content",

            "data": [

              {

                "html": "ist \nLösung mit <em>Mindbreeze</em> InSpire\nContract Management...Das Schönste an <em>Mindbreeze</em> InSpire ist"

              }

            ]

          }

        ],

        "order": {

          "num": 534155

        },

        "group": {

          "str": ""

        }

      },

      {

        "id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/de/blog/fabasoft-mindbreeze-2012-fall-release.html:",

        "location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjk0OQ==",

        "rank_score": 53.3515,

        "relevance_score": 53.3515,

        "properties": [

          {

            "id": "title",

            "name": "Title",

            "data": [

              {

                "html": "Fabasoft <em>Mindbreeze</em> 2012 Fall Release"

              }

            ]

          },

          {

            "id": "content",

            "name": "content",

            "data": [

              {

                "html": "Fabasoft <em>Mindbreeze</em> 2012 Fall Release...Inhalte erreicht. Unsere <em>Mindbreeze</em> Enterprise Architektur"

              }

            ]

          }

        ],

        "order": {

          "num": 533515

        },

        "group": {

          "str": ""

        }

      },

      

    ],

    "prev_avail": false,

    "next_avail": true,

    "order_direction": "DESCENDING",

    "per_service_dataset": [

      {

        "id": "https://demo.mindbreeze.com/public/",

        "termination_cause": "COUNT_LIMIT",

        "paging_state": {

          "id": "unnamed",

          "state": "\n\u00010\u0010\u0000\u0018\u0001",

          "digest": "dBCFawAIMiGsGEflr6JYhw=="

        }

      }

    ]

  },

  "groupable": [

    {

      "name": "Author",

      "localized_name": "Author"

    },

    {

      "name": "Category",

      "localized_name": "Category"

    },

    

  ],

  "show_query_spelling_alternatives": false,

  "order_direction_available": true

}

Fields in the Search ResultPermanent link for this heading

search_requestPermanent link for this heading

The search request.

alternativesPermanent link for this heading

Contains information about alternative search terms that are grouped by type. The entry with id user_query contains the user's search term after applying all synonyms or other query transformation rules. The entry with id query_spelling provides spell-checking.

The entries each contain lists of alternatives (entries). These lists contain the search term in html, an estimate of the expected results in count and the in query_expr.

{

  "id": "user_query",

  "name": "user_query",

  "entries": [{

    "html": "mindbreeze",

    "count": 1,

    "query_expr": {

      "unparsed": "mindbreeze"

    }

  }]

}

namePermanent link for this heading

Name of the search. Can be sent in search_request with name.

estimated_countPermanent link for this heading

An estimate of the expected number of hits.

facetsPermanent link for this heading

A list of filters for the current search. id contains the name of the metadata, name contains the display name.

The entries are located in entries. With html the value can be accessed, with count the estimated number of results, and with query_expr the that can be used to restrict. Filters can also be hierarchical, in that case there is also an entries field for a value.

order_criteria and order_direction (ASCENDING, DESCENDING) show the sorting of the filters.

Sorting description order_criteria

COUNT

Estimated number

HTML

Textual description (e.g. August before July)

VALUE

Value (e.g. July before August)

{

  "id": "mes:date",

  "name": "Date",

  "entries": [{

    "html": "2016",

    "count": 676,

    "query_expr": {

      …

    },

    "entries": [{

      "html": "July",

      …

    }],

  }],

  "order_criteria": "COUNT",

  "order_direction": "DESCENDING"

}

orderbyPermanent link for this heading

Contains the property by which the results are sorted.

orderablePermanent link for this heading

A list of properties that can be used for sorting. Each one with name (name) and display name (localized_name).

available_propertiesPermanent link for this heading

A list of properties that can be used for the display. Each with a name (name) and display name (localized_name).

available_facetsPermanent link for this heading

A list of properties that are available as filters. Each with name (name) and display name (localized_name).

resultsetPermanent link for this heading

Contains the list of results (results), information to scroll (prev_avail, next_avail, per_service_dataset) and the sorting order of the results (order_direction, ASCENDING or DESCENDING).

prev_avail contains true, if you can scroll backwards in the result list, and next_avail, if you can scroll forwards.

per_service_dataset has the id of the requested services

termination_cause

COUNT_LIMIT

More results available

NO_MORE_RESULTS

No more results available

TIMEOUT

Search delivered less than count results and a time-out has occurred during one phase of the search. The message here is that there could be more results. The total time-out of the search occurs in stages

ABORT

Search was discontinued

SHORTCUTTED

The search was canceled because there are no results with the given search restriction by data sources

UNKNOWN

Unknown

and paging_state to scroll.

{

  "id": "https://demo.mindbreeze.com/public/",

  "termination_cause": "COUNT_LIMIT",

  "paging_state": {

    "id": "unnamed",

    "state": "\n\u00010\u0010\u0000\u0018\u0001",

    "digest": "dBCFawAIMiGsGEflr6JYhw=="

  }

}

ResultsPermanent link for this heading

properties contains the list of the requested metadata, each with name (id) and display name (name), and a list of the entries (data).

If was used in the search query, group contains the value.

id is an identifier of the hit; location is required for the preview. rank_score can be used for sorting and relevance_score contains the relevance scores.

{

  "id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/",

  "location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwa",

  "rank_score": 53.4155,

  "relevance_score": 53.4155,

  "properties": [{

    "id": "title",

    "name": "Title",

    "data": [{

      "html": "Vertragsmanagement | <em>Mindbreeze</em>"

    }]

  },{

    "id": "content",

    "name": "content",

    "data": [{

      "html": "ist \nLösung mit <em>Mindbreeze</em> "

    }]

  }],

  "order": {

    "num": 534155

  },

  "group": {

    "str": ""

  }

}

groupablePermanent link for this heading

A list of properties that can be used for grouping. Each with a name (name) and display name (localized_name).

show_query_spelling_alternativesPermanent link for this heading

Indicates whether query spelling alternatives (for example, a “Did you mean?“) may be present in the response. The query contains the option alternative_query_spelling_max_estimated_count, which is checked using the estimated_count.

order_direction_availablePermanent link for this heading

Contains true if the sort order can be specified in the query.

ScenariosPermanent link for this heading

Each of the following sections covers one search task, and can be combined with one another.

Search TermsPermanent link for this heading

The search term(s) is submitted using the options user.query and user.constraint, the difference being that user.query occurrences are highlighted in the results, whereas user.constraint occurrences are not.

user.query: Permanent link for this heading

{

  "query": {

    "unparsed": "mindbreeze"

  },

  "count": 5,

  "properties": [{

    "name": "content",

    "formats": ["HTML"]

  }]

}

Result: Fabasoft <em>Mindbreeze</em> 2012 Fall Release

constraintPermanent link for this heading

{

  "constraint": {

    "unparsed": "mindbreeze"

  },

  "count": 5,

  "properties": [{

    "name": "content",

    "formats": ["HTML"]

  }]

}

Result: We are delighted that you have chosen Mindbreeze InSpire

Query ExpressionsPermanent link for this heading

Both structured and unstructured search terms can be submitted. This means that a search in metadata, AND, OR, NOT, NEAR and range searches are possible.

Unstructured SearchPermanent link for this heading

The value unparsed corresponds to the search the way it can be entered into the search field.

{

  "unparsed": "mindbreeze OR inpsire"

}

Term SearchPermanent link for this heading

Finds words and parts of words. The example finds hits with “mind“, but also e.g. “mindbreeze“.

{

  "term": "mind"

}

Phrase SearchPermanent link for this heading

Finds only occurrences of the complete phrase.

{

  "quoted_term": "mindbreeze inspire"

}

Metadata SearchPermanent link for this heading

label specifies the metadata that is being searched, for example:

The following example searches all HTML documents analogous to extension:html:

{            

  "label": "extension",

  "unparsed": "html"

}

AND-OperationPermanent link for this heading

and contains a list of query expressions with AND-operators.

mindbreeze AND inspire becomes

"query": {                  

  "and": [{                

    "unparsed": "mindbreeze"

  },{                      

    "unparsed": "inspire"  

  }]                        

}    

OR-OperationPermanent link for this heading

or contains a list of query expressions with OR-operators.

mindbreeze OR inspire becomes

"query": {                  

  "or": [{                

    "unparsed": "mindbreeze"

  },{                      

    "unparsed": "inspire"  

  }]                        

}

NEAR-OperationPermanent link for this heading

Analogous to mindbreeze NEAR inspire

"query": {                        

  "near": ["mindbreeze", "inspire"]

},        

NOTPermanent link for this heading

not is added to an existing query expression in order to narrow down the results. Contains a list of query expressions.

mindbreeze NOT classification becomes

"query": {                      

  "unparsed": "mindbreeze",      

  "not": [{                      

    "unparsed": "classification"

  }]                            

}

Term-Range QueriesPermanent link for this heading

The search term 2015 TO 3015” becomes:

{      

  "from": "2015",

  "to": "3015"  

}

Structured QueriesPermanent link for this heading

Structured queries require a specific property, and the property should support the corresponding form of the query.

Search with Regular ExpressionsPermanent link for this heading

{                          

  "label": "mes:key",                

  "regex": ".*product-[\\d\\d\\d\\d]"

}                                  

Numeric Queries  Permanent link for this heading

If a property on the document is a number or a size specification with a unit (such as time in milliseconds since 1/1/1970 (UTC) information in bits), a composite numerical search can be made for it. In addition to an AND operation, an OR operation can be used.

{

  "label": "mes:date",

  "and": [{

    "num": 1451606400000,

    "cmp": "GE",

    "unit": "ms_since_1970"

  },{

    "num": 1483228799999,

    "cmp": "LE",

    "unit": "ms_since_1970"

  }]

}

cmp expressions

EQ

=

LT

<

GT

>

LE

GE

Expressions of unit that can be specified explicitly:

ms_since_1970

identifies the number of milliseconds since 1/1/1970 UTC

Other than that, the base unit in an information amount, e.g. bytes, will be supported.

Number of ResultsPermanent link for this heading

The count option specifies the number of results returned by a query.

{

  "query": {

    "unparsed": "test"

  },

  "count": 5

}

The default is 0.  

Apply FiltersPermanent link for this heading

The search result contains a filter for path:

"facets": [{

  "id": "path",

  "name": "Path",

  "entries": [{

    "html": "de",

    "count": 413,

    "query_expr": {

      "label": "path",

      "regex": "^\\Qde\\E$",

      "description": "de",

      "id": "de",

      "value": {

        "str": "de"

      }

    },

    "value": {

      "str": "de"

    }

  },{

    "html": "blog",

    "count": 171,

    "query_expr": {

    "label": "path",

    "regex": "^\\Qblog\\E$",

    "description": "blog",

    "id": "blog",

      "value": {

        "str": "blog"

      }

    },

    "value": {

      "str": "blog"

    }

  },{

    "html": "career",

    "count": 29,

    "query_expr": {

      "label": "path",

      "regex": "^\\Qcareer\\E$",

      "description": "career",

      "id": "career",

      "value": {

        "str": "career"

      }

    },

    "value": {

      "str": "career"

    }

  },…]

}]

To select the value de, a query expression with the following form is added to user.constraints:

{

  "label": "<metadata>",

  "id": "<custom id>",

  "filtered_name": "<display name>",

  "filter_base": [<list of query expressions of all selected values>],

  "filtered": [<list of query expressions of all non-selected values >]

  }

Specifically, de was selected here as the only value:

{

  "user": {

    "query": {

      "unparsed": "mindbreeze"

    },

    "constraints": [{

      "label": "path",

      "id": "filter_path",

      "filtered_name": "Path",

      "filter_base": [{

        "label": "path",

        "regex": "^\\Qde\\E$",

        "description": "de",

        "id": "de",

        "value": {

          "str": "de"

        }

      }],

      "filtered": [{

        "label": "path",

        "regex": "^\\Qblog\\E$",

        "description": "blog",

        "id": "blog",

        "value": {

          "str": "blog"

        }

      },

      {

        "label": "path",

        "regex": "^\\Qcareer\\E$",

        "description": "career",

        "id": "career",

        "value": {

          "str": "career"

        }

      }, …]

    }]

  },

  "count": 5,

  "facets": [{

    "name": "path",

    "formats": ["HTML"]

  }]

}

MetadataPermanent link for this heading

Each query may require different filters and metadata. For this, use the options facets and properties.  name contains the name of the metadata item and formats contains a list of desired formats:

"properties": [{    

  "name": "title",  

  "formats": ["HTML"]

}]

"facets": [{            

  "name": "extension",  

  "formats": ["PROPERTY"]

}]

Formats

HTML

{

  "id": "title",

  "name": "Title",

  "data": [{

    "html": "Vertragsmanagement | <em>Mindbreeze</em>"

  }]

}

{

  "id": "mes:date",

  "name": "Date",

  "data": [{

    "html": "7/11/16 2:07 PM"

  }]

}

VALUE

{

  "id": "title",

  "name": "Title",

  "data": [{

    "value": {

      "str": "Vertragsmanagement | Mindbreeze"

    }

  }]

}

{

  "id": "mes:date",

  "name": "Date",

  "data": [{

    "value": {

      "num": 1468247114000,

      "unit": "ms_since_1970"

    }

  }]

  }

PROPERTY

{

  "id": "title",

  "name": "Title",

  "properties": [{

    "id": "title",

    "name": "Title",

    "data": [{

      "html": "Vertragsmanagement | <em>Mindbreeze</em>",

      "value": {

        "str": "Vertragsmanagement | Mindbreeze"

      }

    }]

  }]

}

{

  "id": "mes:date",

  "name": "Date",

  "properties": [{

    "id": "mes:date",

    "name": "Date",

    "data": [{

      "html": "7/11/16 2:25 PM",

      "value": {

        "num": 1468247114000,

        "unit": "ms_since_1970"

      }

    }]

  }]

}

Default for facets and properties is empty. The filter values for mes:date are always delivered.

The search response will contain a list of all metadata available for the and as a .

PagingPermanent link for this heading

The search response contains resultset.prev_avail and resultset.next_avail to let you know whether you can page backwards and/or forwards.

"resultset": {

  …

  "prev_avail": false,

  "next_avail": true,

  "per_service_dataset": [

    {

      "id": "https://demo.mindbreeze.com/public/",

      "termination_cause": "COUNT_LIMIT",

      "paging_state": {

        "id": "unnamed",

        "state": "\n\u00010\u0010\u0000\u0018\u0001",

        "digest": "dBCFawAIMiGsGEflr6JYhw=="

      }

    }

  ]

}

To page, indicate the direction with paging.direction (PREV, NEXT) and accept resultset.per_service_dataset.paging_state in paging_states:

{                                                

  "query": {                                    

    "unparsed": "mindbreeze"                    

  },                                            

  "count": 5,                                    

  "paging_states": [{                            

    "id": "unnamed",                            

    "state": "\n\u00010\u0010\u0000\u0018\u0001",

    "digest": "dBCFawAIMiGsGEflr6JYhw=="        

  }],                                            

  "paging": {                                    

    "direction": "NEXT"                          

  }                                              

}                      

SortingPermanent link for this heading

orderby contains the metadata used for sorting. order_direction (ASCENDING, DESCENDING) determines the order used.

{                              

  "query": {                    

    "unparsed": "mindbreeze"    

  },                            

  "count": 5,                  

  "orderby": "mes:date",        

  "order_direction": "ASCENDING"

}            

The defaults are mes:relevance and DESCENDING.

The search response will contain a list of all the .

GroupingPermanent link for this heading

groupby.property contains the metadata used to do the grouping.

{                          

  "query": {                

    "unparsed": "mindbreeze"

  },                        

  "count": 5,              

  "groupby": {              

    "property": "extension"

  }                        

}  

The results contained in group contain the grouping value.                    

"results": [

  {

    "id": "Web:wwwmindbreezecom:h…",

    …

    "group": {

      "str": "html"

    }

The search response will contain a list of all g.

Localization of the Display Names and ValuesPermanent link for this heading

user_context.locale specifies the locale with which the display names are translated and the numbers and dates are formatted.

{                                

  "query": {                    

    "unparsed": "mindbreeze"    

  },                            

  "count": 5,                    

  "user_context": {              

    "locale": "de-AT"            

  },                            

  "properties": [{              

    "name": "extension",        

    "formats": ["HTML", "VALUE"]

  }]                            

}

Time ZonePermanent link for this heading

user_context. utc_time_zone_differential_in_seconds indicates the seconds between UTC and the current time zone. Thus, the data displayed and the date filters are adjusted to the time zone. For Central European Summer Time, enter 7200.

{                                                

  "query": {                                    

    "unparsed": "mindbreeze"                    

  },                                            

  "count": 5,                                    

  "user_context": {                              

    "locale": "de-AT",                          

    "utc_time_zone_differential_in_seconds": 7200

  },                                            

  "properties": [{                              

    "name": "extension",                        

    "formats": ["HTML", "VALUE"]                

  }]                                            

}                                                

Time-outPermanent link for this heading

timeout_in_seconds determines the maximum duration of the search.

{                          

  "query": {                

    "unparsed": "mindbreeze"

  },                        

  "count": 5,              

  "timeout_in_seconds": 3  

}                          

Sample TextsPermanent link for this heading

content_sample_length specifies the maximum length in characters of the sample text for the results.

{                              

  "query": {                    

    "unparsed": "mindbreeze"    

  },                            

  "count": 5,                  

  "content_sample_length": 1000,

  "properties": [{              

    "name": "content",          

    "formats": ["HTML"]        

  }]                            

}                              

The default is 100 characters.

Relevance FactorsPermanent link for this heading

There is a more detailed white paper with more information about relevance. This section deals with the structure.

With the property relevance_factors, the individual relevance factors can be set, such as the timeliness of the hit, the proximity of results to each other in the document, etc. The total amount of all the factors is determined and then the individual parameters are relatively weighted.

recency

Topicality, timeliness

term_frequency

Frequency of hits in the document

doc_frequency

Standardized frequency relative to the document size

term_proximity

Proximity of the terms to each other

zone_boost_exponent

Weighting of the zones (metadata)

term_boost_exponent

Weighting of the term boostings

doc_boost_exponent

Weighting of the document boostings

{                                    

  "user": {                          

    "query": {                        

      "unparsed": "mindbreeze"        

    }                                

  },                                  

  "relevance_factors": {              

    "recency": 15,                    

    "term_frequency": 5,              

    "doc_frequency": 0,              

    "term_proximity": 35,            

    "term_inverse_zone_frequency": 45,

    "zone_boost_exponent": 50,        

    "term_boost_exponent": 50,        

    "doc_boost_exponent": 100        

  },                                  

  "boostings": [{                    

    "id": "url",                      

    "factor": 2                      

  }],                                

  "term_boost_factor": {              

    "term_boost_factor": 5,          

    "ngram_boost_factor": 10,        

    "congruence_boost_factor": 15,    

    "distance_boost_reduction": 20    

  }                                  

}              

The search response for each result contains the .

Properties and Document BoostingsPermanent link for this heading

Properties BoostPermanent link for this heading

{                                    

  "user": {                          

    "query": {                        

      "unparsed": "mindbreeze"        

    }                                

  },                                  

  "boostings": [{                    

    "id": "url",                      

    "factor": 2                      

  }]                                  

}                                     

Document Boost Based on Search TermsPermanent link for this heading

{                                    

  "user": {                          

    "query": {                        

      "unparsed": "mindbreeze"        

    }                                

  },                                  

  "boostings": [{                    

    "id": "product_boost",            

    "query_expr": {                  

      "label": "mes:key",            

      "regex": ".*product-[\\d\\d\\d\\d]"

    }                                

    "factor": 2                      

  }]                                 

}