Sure, you can handle it. But should you?
Let our experts manage the tech maintenance while you focus on your business.
Let our experts manage the tech maintenance while you focus on your business.
Interface Description
api.v2.search
Introduction
This document deals with the Mindbreeze Web API for querying search results. It was implemented on the basis of the documentation api.v2.search on help.mindbreeze.com. Examples are used to explain and illustrate the content. The primary focus of these examples is to highlight the backend use. The communication of the API is performed in this documentation using the Chromium browser and the Postman plug-in. The API uses the JSON protocol for communication.
Search queries are sent as HTTP POST to a client service. The path for search queries is: <Client Service URL>/api/v2/search
A JSON document describing the search query is sent in the body of the HTTP request. How this JSON document should look is described in Chapter 3 and Chapter 4.
The response received is also a JSON document. This is described in Chapter 2.
Fields in the search result
search_request
The search request.
alternatives
Contains information about alternative search terms that are grouped by type.
The entry with id user_query shows the expanded query of the user, if an expansion like synonyms or stemming have been transformed. If it is not shown, the query can be taken from the search_request part of the search response (search_request.user.query).
The entry with id query_spelling provides spelling correction.
Each entry contains a list of alternatives (entries).
This list contains the search term in html, an estimate of the expected results in count, and the query expression in query_expr.
{
"id": "user_query",
"name": "user_query",
"entries": [{
"html": "mindbreeze",
"count": 1,
"query_expr": {
"unparsed": "mindbreeze"
}
}]
}
name
The name of the search. Can be sent in search_request with name.
estimated_count
Estimation of the expected number of hits.
facets
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. The value can be accessed with html, the estimated number of results can be accessed with count, the query expression that can be used for the constraint can be accessed with query_expr. Filters can also be hierarchical, in which case the value also has an entries field.
order_criteria and order_direction (ASCENDING, DESCENDING) denote the sorting of the filters.
Sort specification 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"
}
orderby
Contains the property by which the results are sorted.
orderable
A list of properties that can be used for sorting, each with name (name) and localized display name (localized_name).
available_properties
A list of properties that can be used for display, each with name (name) and localized display name (localized_name).
available_facets
A list of properties that are available as filters, each with name (name) and localized display name (localized_name).
resultset
Contains the list of results (results), information about scrolling (prev_avail, next_avail, per_service_dataset), and the sort direction 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 contains the id of the requested service, termination_cause.
COUNT_LIMIT | More results available |
NO_MORE_RESULTS | No more results available |
TIMEOUT | The search delivered fewer hits than count, and a timeout occurred in a phase of the search. The message here is that there could be even more hits. The entire search timeout is applied in phases. |
ABORT | The search was cancelled |
SHORTCUTTED | The search was cancelled because there are no results with the given search constraint for data sources. |
UNKNOWN | Unknown |
and paging_state for scrolling.
"id": "https://demo.mindbreeze.com/public/",
"termination_cause": "COUNT_LIMIT",
"paging_state": {
"id": "unnamed",
"state": "\n\u00010\u0010\u0000\u0018\u0001",
"digest": "dBCFawAIMiGsGEflr6JYhw=="
}
}
Results
properties contains the list of requested metadata, each with name (id) and display name (name), as well as a list of entries (data).
If grouping was used for the query, group contains the value.
id is an identifier of the hit, location is needed for the preview. rank_score can be used for sorting and relevance_score contains the relevance score.
{
"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": ""
}
}
groupable
A list of properties that can be used for grouping, each with name (name) and localized display name (localized_name).
show_query_spelling_alternatives
Indicates whether query spelling alternatives (such as “Did You Mean“) may be present in the response.
In the request, there is the option alternative_query_spelling_max_estimated_count. This is checked here with estimated_count.
Note: if contrary to expectations no query spelling alternatives appear and own logical operators are used in the query, see: Notes on Query Spelling Alternatives
disable_alternatives_query_spelling_query_term_count_threshold
Can be specified to override the index option "Disable Did You Mean Term Count Threshold", see also Documentation - Mindbreeze InSpire, Section: Query Settings.
Did You Mean is only performed if the number of terms in the query (minus stop words, if configured) does not exceed the configured value.
The following values have a special meaning:
- -1: No limitation, the number of terms is ignored.
- 0 (default): "Maximum Word NGram Length" multiplied by 5.
order_direction_available
Contains true if the sort order can be specified in the search query.
sort_date_facets_by_value
Indicates how date-filters are sorted. „true“ sorts by year and month and „false“ sorts by number of results.
Type: Boolean
sample_text_mark_entity_types
Specifies which entities should be highlighted in a result. Type: Array
Example:
"sample_text_mark_entity_types":["person","organization","date","misc","location"]
sample_text_mark_all_entity_types
Specify whether to highlight all available entities in a result. Type: Boolean
alternatives_query_spelling_max_estimated_count
See show_query_spelling_alternatives
source_context
Provides addistional constraints for the search request.
"source_context": {
"constraints": [{
id: "searchcontainer",
unparsed: "extension:PDF"
}]
}
query_context
Contains detailed information about the application and the search itself, which can be viewed in the app.telemetry.
Example:
"query_context": {
"application_id": "Default Application",
"prev_query_id": "1649054355394",
"properties": [{
"key": "my_extension",
"value": "html"
}],
"query_id": "1649054355849",
"query_trigger_action": "submit",
"refinement_id": "164905355394",
"prev_refinement_id": "164905344394"
}
query_context_user_query
Contains the user query, can be viewed in the app.telemetry log pool and is of type “string”.
answers and formatted_answers
Provides a list of answers. NLQA must be configured for answers to be available, see Whitepaper – Natural Language Question Answering (NLQA).
The information provided by the fields “answers” and “formatted_answers” can be configured with the setting “answer_format”. The following options are available:
- UNFORMATTED_ANSWERS (default value) – The field „answers“ provides information.
- FORMATTED_ANSWERS – The field „answers“ provides information. HTML formatting is added to reproduce the structure of the original document (see the chapter Sentence Transformer Settings).
- FORMATTED_AND_UNFORMATTED_ANSWERS - The fields „answers“ and „formatted_answers“ provide information. HTML formatting is added to the field „formatted_answers“ to reproduce the structure of the original document (see the chapter Sentence Transformer Settings).
Example without HTML formatting:
"score": 0.07456222772598267,
"similarity_score": 0.7456222772598267,
"text": {
"text": "Over 450 connectors are available with Mindbreeze …",
"context_before": "… enables experts to create their own apps.",
"context_after": "Integration into your workplace …",
"text_start_pos": 1120
},
"properties": [ … ]
}
Example with HTML formatting:
"score": 0.07456222772598267,
"similarity_score": 0.7456222772598267,
"text": {
"text": "Over <b>450 connectors</b> are available with Mindbreeze …",
"context_before": "… enables experts to create their own apps.",
"context_after": "<a href="http://example.com/integration">Integration into your workplace</a> …",
"text_start_pos": 1120
},
"properties": [ … ]
}
answers
The field “answers” provides the following information:
Element | Description | ||||||||||
score | A value between 0 and 1 representing the quality of an answer. The better the answer, the higher the value in the score. | ||||||||||
similarity_score | A value between 0 and 1 representing the quality of an answer. The better the answer, the higher the value in the score. This value ignores any relevance boosting. | ||||||||||
properties | All the properties of the original document. | ||||||||||
property_name | The property of the document from which the answer was extracted. | ||||||||||
text | An object with the following information:
|
formatted_answers
The field “formatted_answers” provides information by setting answer_format to „FORMATTED_AND_UNFORMATTED_ANSWERS“ (see Sentence Transformer Settings). While the field „answers“ provides unformatted information, the field „formatted answers“ now contains information with HTML formatting to reproduce the structure of the original document.
Each „answer” has one associated formatted_answer which is identical, except for the HTML formatting.
If only formatted or unformatted answers are required, the field „formatted_answers” remains empty.
See the chapter answers and formatted_answers for an example with and without HTML formatting.
Fields in the search query
Types of search
Using the example of a search for the term “Mindbreeze Inspire”, this chapter deals with the three types of search that you can execute using the API described in this document.
Unstructured search
The value unparsed corresponds to the way the search can be entered in the search field.
{
"unparsed": "mindbreeze OR inspire"
}
Term search
Finds words and parts of words. The example below finds hits with “mind”, but also with e.g. “mindbreeze”.
{
"term": "mind"
}
Phrase search
Finds only occurrences of the complete phrase.
{
"quoted_term": "mindbreeze inspire"
}
Similar search
NLQA returns results and answers to the question asked.
{
"similar": "How can I install a connector for Mindbreeze Inspire?"
}
You have the possibilities to configure which and how the answers are delivered.
Extended answer context
This setting defines the length of the text of the found answer. The default value is "default". If you want more context in your answer you can change this to "large".
{
"similar": "How can I install a connector for Mindbreeze Inspire?",
"textRegion": "large"
}
Hint: With the setting "large" the similarity score of each answer gets lower.
Minimal Similarity Score (“Minimal Score”)
With this setting all answers will be excluded which have a lower similarity score than the given similarity score in the query.
{
"similar": " How can I install a connector for Mindbreeze Inspire?",
"minScore": 0.25
}
Hint: The defined value for the minimal similarity score from the Client Service gets overwritten with the defined one just for this request.
Scrolling
To restrict the size of the HTTP response, not all search results are returned in the HTTP response, but rather only an extract of the search results. In Request JSON you can define the maximum number of search results that can be contained in the response in count.
{
"query": {
"unparsed": "mindbreeze"
},
"count": 5
}
The search response contains resultset.prev_avail and resultset.next_avail to tell you whether you can scroll 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 scroll, indicate the direction with paging.direction (PREV, NEXT) and accept with 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"
}
}
Paging
If paging is activated (the option max_page_count is set), then the search response contains resultset.result_pages.
"result_pages": {
"qeng_ids": [{
"service_id": "https://demo.mindbreeze.com/public/",
"qeng_id": "https://demo.mindbreeze.com:23300",
"digest": "t/y1e0hHmK/VzgZNMwczHA=="
}
], {
"pages": [{
"starts": [0],
"counts": [5],
"current_page": true,
"page_number": 0
}, {
"starts": [5],
"counts": [5],
"page_number": 1
}, {
"starts": [10],
"counts": [5],
"page_number": 2
}, {
"starts": [15],
"counts": [5],
"page_number": 3
}, {
"starts": [20],
"counts": [5],
"page_number": 4
}
],
"page_size": 5,
"page_count": 5,
"more_avail": true
},
"page_size": 5,
"page_count": 5,
"more_avail": true
}
The result_pages return by search response is added to subsequent search request with the current_page flag set on the selected page.
"result_pages": {
"qeng_ids": [{
"service_id": "https://demo.mindbreeze.com/public/",
"qeng_id": "https://demo.mindbreeze.com:23300",
"digest": "t/y1e0hHmK/VzgZNMwczHA=="
}
], {
"pages": [{
"starts": [0],
"counts": [5],
"page_number": 0
}, {
"starts": [5],
"counts": [5],
"current_page": true,
"page_number": 1
}, {
"starts": [10],
"counts": [5],
"page_number": 2
}, {
"starts": [15],
"counts": [5],
"page_number": 3
}, {
"starts": [20],
"counts": [5],
"page_number": 4
}
],
"page_size": 5,
"page_count": 5,
"more_avail": true
},
"page_size": 5,
"page_count": 5,
"more_avail": true
}
Logical operators
Explanation
Queries can also be linked with AND, OR, NOT, and many other logical operators, as explained in the documentation on help.mindbreeze.com. In the following example, two queries are linked with an AND operator. The results must match both mindbreeze and About.
Code
{
"query": {
"and":[{
"unparsed": "mindbreeze"
},{
"unparsed": "About"
}]
}
"count": 5,
"properties": [{
"name": "title",
"formats": ["HTML"]
},{
"name": "content",
"formats": ["HTML"]
}]
}
Result
…
"resultset": {
"results": [
{
"id": "SAP KMC:Default:/irj/go/km/docs/documents/MarketingPRTestdaten/DateienWebsite/Fabasoft%20Sales%20Kit%20(EN)/Mindbreeze/2013-02-27%20Mindbreeze%20Sales%20(English%2c%2016-9).pptx:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzM5OjUzNzE=",
"rank_score": 36.9355,
"relevance_score": 36.9355,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "2013-02-27 <em>Mindbreeze</em> Sales (English, 16-9).pptx"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "<em>About Mindbreeze</em> \nVienna, February 28...– 10:30 \t<em>Mindbreeze</em> \n\t10:30 – 12:00 \t<em>Mindbreeze</em> InSite \n\t12:00...– 14:30 \t<em>Mindbreeze</em> InSpire \n\t14:30...– 16:00 \t<em>Mindbreeze</em> InApp \n\t16:00...– 17:30 \t<em>Mindbreeze</em> InTouch \n \n \n \n \n<em>Mindbreeze</em> Products \n \nLIGHT IN...arbeitet, findet mit <em>Mindbreeze</em> Enterprise Search relevante...website: http://insite.<em>mindbreeze</em>.com \nBenefits and"
}
]
}
],
"order": {
"num": 369355
},
"group": {
"str": ""
}
},…
Near
Explanation
Using near, search terms can be restricted to the distance of occurrences. If for example, “mindbreeze NEAR inspire” is searched, the distance between “mindbreeze” and “inspire” may not be more than 6 words for the result of the query to be matched. The order is ignored (mindbreeze NEAR inspire == inspire NEAR mindbreeze).
Code
{
"query": {
"near": ["mindbreeze","inspire"]
}
"count": 1,
"properties": [{
"name": "title",
"formats": ["HTML"]
},{
"name": "content",
"formats": ["HTML"]
}]
}
Result
"resultset": {
"results": [
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/de/inspire-training-feb2017:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjM1MTA=",
"rank_score": 43.8645,
"relevance_score": 43.8645,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "<em>Mindbreeze InSpire</em> Training"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "<em>Mindbreeze InSpire</em> Training\nDauer: 3...wichtigsten Neuerungen von <em>Mindbreeze InSpire</em>. Wir freuen uns...richtigen Umgang mit <em>Mindbreeze InSpire</em> und im Speziellen...Einführung in das <em>Mindbreeze InSpire</em> SDK Entwicklung\n\tDetails...Sicherheitsmodells\n Know-how: <em>Mindbreeze InSpire</em> SDK (z. B"
}
]
}
],
"order": {
"num": 438645
},
"group": {
"str": ""
}
TO operator
Explanation.
Moreover, you can also apply the TO operator automatically for numeric values. This is even possible for numeric values located in continuous text in a result. In our example, only the results that contain a number between 100 and 103 are returned.
Code
{
"query": {
"from":"100",
"to":"103"
}
"count": 5,
"properties": [{
"name": "title",
"formats": ["HTML"]
},{
"name": "content",
"formats": ["HTML"]
}]
}
Result
…
"resultset": {
"results": [
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/de/presse/100-companies-that-matter.html:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjM3MTA=",
"rank_score": 39.933,
"relevance_score": 39.933,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "<em>100</em>-companies-that-matter.html"
}
]
}
],
"order": {
"num": 399330
},
"group": {
"str": ""
}
},…
Regular expressions
Explanation
With the Mindbreeze search API, it is also possible to place a regex instead of a normal query. If the regex matches, the result is returned. It’s important to note that the backslash in JSON must escaped separately. This means that with a regex escape, two backslashes are required rather than just one (1 for JSON and 1 for regex escape). In our example, the document has to match the regex pattern in mes:key (beginning of an URL) in order for it to be returned. This only works with metadata that are regex matchable or aggregatable. Please note that regex can only be searched for in specific metadata and not without a label.
Code
{
"query": {
"label":"mes:key"
"regex": "https:\\/\\/www\\.mindbreeze\\.com\\/de.*"
}
"count": 1,
"properties": [{
"name": "title",
"formats": ["HTML"]
},{
"name": "content",
"formats": ["HTML"]
}]
}
Result
"resultset": {
"results": [
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/de/mindbreeze-basic-training-oktober-2015.html:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjY=",
"rank_score": 0,
"relevance_score": 0,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "Mindbreeze Basic Training / Schulung"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "Mindbreeze Basic Training / Schulung\nTrainingsdatum: 13.10.2015\nOrt: Mindbreeze Academy, Honauerstraße 4, 4020 Linz, Austria\nDauer: 1 Tag, 09:00 - 17:00\nPreis: EUR 600,-- (exkl. MWSt.) pro Person\nTeilnehmeranzahl: mindestens 5 Personen\nLevel: Einsteiger\nVorausgesetzte Kurse: keine\nSprache: Englisch ¹)\n¹) Falls sich ausschließlich deutschsprachige Teilnehmer anmelden, wird auch die Ausbildung auf Deutsch gehalten.\nKommen Sie zu uns und erfahren Sie direkt von den Mindbreeze-Experten alles üb..."
}
]
}
],
"order": {
"num": 0
},
"group": {
"str": ""
}
}
Time spans
Explanation
With the Mindbreeze InSpire search API, it is possible to return content that occurs within a certain period of time as a result. Timestamps (UNIX time) are used as a limiter. In our case, we want to show all results from January 1, 2016 to June 7, 2017 at 10:26 UTC. In addition to an AND operator, you can also use an OR operator for the two time stamps.
Code
{
"query": {
"label": "mes:date",
"and": [{
"num": 1451606400000,
"cmp": "GE",
"unit": "ms_since_1970"
}, {
"num": 1496831176874,
"cmp": "LE",
"unit": "ms_since_1970"
}
]
}
"count": 1,
"properties": [{
"name": "title",
"formats": ["HTML"]
}, {
"name": "content",
"formats": ["HTML"]
}
]
}
Result
"resultset": {
"results": [
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/inspire-contact:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjQ=",
"rank_score": 0,
"relevance_score": 0,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "Contact"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "Contact\nWe are delighted that you have chosen Mindbreeze InSpire.\nPlease name a contact person and suitable dates for the on-site support.\nFor other data sources, please add also the IP address or DNS name of the data sources. The ports that are required to these data sources have to be unlocked bidirectional between Mindbreeze Appliance and data sources."
}
]
}
Notes on Query Spelling Alternatives ("Did you mean")
Explanation
The query spelling alternatives are calculated based on the original user query. The original user query is taken from the query from the unparsed-value (directly or within an and-operator).
If the query does not conform to this form (for example, because additional logical operators were used) then the original user query must be passed as a separate original_unparsed parameter.
(If this is not done, then no original user query can be determined and no query spelling alternatives can be provided).
Code
{
"user": {
"query": {
"and": [
{
"or": [
{
"unparsed": "\"eamples\""
},
{
"unparsed": "eamples"
}
]
}
],
"original_unparsed": "eamples"
}
}
}
Result
{
...
"alternatives": [
{
"id": "query_spelling",
"name": "query_spelling",
"entries": [
{
"html": "<em>examples</em>",
"count": 863,
"query_expr": {
"unparsed": "examples",
"description": "examples"
}
}
]
}
],
...
"show_query_spelling_alternatives": true,
"status_messages": [
{
"id": "no_results",
"info": "No results found"
}
]
}
Filter/Facets
Explanation
With the Mindbreeze search API, it is possible to specify parameters that return a filter/facet. In our example, a filter/facet for the file extension/metadata extension will be returned in addition to the metadata. Important information about the filters includes, for instance, the number of results that have a certain filter value. As an example, the number of .png files in the search for “mindbreeze” is marked in bold.
Code
{
"query": {
"unparsed": "mindbreeze"
},
"count": 1,
"properties": [{
"name": "title",
"formats": ["HTML"]
},{
"name": "content",
"formats": ["HTML"]
}],
"facets":[
{
"name":"extension"
"formats":[
"HTML"
]
}
]
}
Advanced Example filter_include_all_descendants
With the option filter_include_all_descendants it is possible to return the complete hierarchy without restriction.
Note: Setting this option may be very expensive, depending on the indexed documents. We recommend doing performance tests with an appropriate number of documents with appropriately shaped metadata to ensure app responsiveness.
Note: This option cannot be set for mes:configuredfacets. It needs to be set explicitly for each filter requested.
Code
{
"query": {
"unparsed": "mindbreeze"
},
"count": 1,
"properties": [{
"name": "title",
"formats": ["HTML"]
},{
"name": "content",
"formats": ["HTML"]
}],
"facets":[
{
"name":"my_hierarchical_filter"
"formats":[
"HTML"
],
"filter_include_all_descendants": true
}
]
}
Result
"facets": [
{
"name": "extension",
"formats": [
"HTML"
]
}
],
"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": 4827,
"facets": [
{
"id": "extension",
"name": "File type",
"entries": [
{
"html": "png",
"count": 1437,
"query_expr": {
"label": "extension",
"regex": "^\\Qpng\\E$",
"description": "png",
"id": "png",
"value": {
"str": "png"
}
},
"value": {
"str": "png"
}
},
{
"html": "html",
"count": 863,
"query_expr": {
"label": "extension",
"regex": "^\\Qhtml\\E$",
"description": "html",
"id": "html",
"value": {
"str": "html"
}
},
"value": {
"str": "html"
}
},
{
"html": "jpg",
"count": 546,
"query_expr": {
"label": "extension",
"regex": "^\\Qjpg\\E$",
"description": "jpg",
"id": "jpg",
"value": {
"str": "jpg"
}
},
"value": {
"str": "jpg"
}
},
{
"html": "gif",
"count": 350,
"query_expr": {
"label": "extension",
"regex": "^\\Qgif\\E$",
"description": "gif",
"id": "gif",
"value": {
"str": "gif"
}
},
"value": {
"str": "gif"
}
},
{
"html": "pdf",
"count": 344,
"query_expr": {
"label": "extension",
"regex": "^\\Qpdf\\E$",
"description": "pdf",
"id": "pdf",
"value": {
"str": "pdf"
}
},
"value": {
"str": "pdf"
}
},
{
"html": "docx",
"count": 261,
"query_expr": {
"label": "extension",
"regex": "^\\Qdocx\\E$",
"description": "docx",
"id": "docx",
"value": {
"str": "docx"
}
},
"value": {
"str": "docx"
}
},
{
"html": "xml",
"count": 211,
"query_expr": {
"label": "extension",
"regex": "^\\Qxml\\E$",
"description": "xml",
"id": "xml",
"value": {
"str": "xml"
}
},
"value": {
"str": "xml"
}
},
{
"html": "msg",
"count": 195,
"query_expr": {
"label": "extension",
"regex": "^\\Qmsg\\E$",
"description": "msg",
"id": "msg",
"value": {
"str": "msg"
}
},
"value": {
"str": "msg"
}
},
{
"html": "zip",
"count": 113,
"query_expr": {
"label": "extension",
"regex": "^\\Qzip\\E$",
"description": "zip",
"id": "zip",
"value": {
"str": "zip"
}
},
"value": {
"str": "zip"
}
},
{
"html": "doc",
"count": 100,
"query_expr": {
"label": "extension",
"regex": "^\\Qdoc\\E$",
"description": "doc",
"id": "doc",
"value": {
"str": "doc"
}
},
"value": {
"str": "doc"
}
},
{
"html": "jpeg",
"count": 77,
"query_expr": {
"label": "extension",
"regex": "^\\Qjpeg\\E$",
"description": "jpeg",
"id": "jpeg",
"value": {
"str": "jpeg"
}
},
"value": {
"str": "jpeg"
}
},
{
"html": "ppt",
"count": 73,
"query_expr": {
"label": "extension",
"regex": "^\\Qppt\\E$",
"description": "ppt",
"id": "ppt",
"value": {
"str": "ppt"
}
},
"value": {
"str": "ppt"
}
},
{
"html": "tif",
"count": 62,
"query_expr": {
"label": "extension",
"regex": "^\\Qtif\\E$",
"description": "tif",
"id": "tif",
"value": {
"str": "tif"
}
},
"value": {
"str": "tif"
}
},
{
"html": "txt",
"count": 58,
"query_expr": {
"label": "extension",
"regex": "^\\Qtxt\\E$",
"description": "txt",
"id": "txt",
"value": {
"str": "txt"
}
},
"value": {
"str": "txt"
}
},
{
"html": "pptx",
"count": 39,
"query_expr": {
"label": "extension",
"regex": "^\\Qpptx\\E$",
"description": "pptx",
"id": "pptx",
"value": {
"str": "pptx"
}
},
"value": {
"str": "pptx"
}
}
],
Advanced Example filter_max_value_count
The maximum number of values returned in the filter are determined by the Client Service via the "Maximum Number of Displayed Values" setting. This setting is used common for all filters. Note: The default value for "Maximum Number of Displayed Values" is 15. We recommend not to set the value too high, as this will affect all filters and may reduce the performance of the search.
With the option filter_max_value_count in the search request it is possible to set the maximum number of values per filter. This allows more values to be requested for individual filters only, without affecting the performance of the entire search.
In this example, two filters/facets are requested. For myname1 no special specifications are made, for myname2, filter_max_value_count is set to the value 5. In the client service configuration "Maximum Number of Displayed Values" is set to the value 3.
In the result, the value of Client Services is used for the filter/facet myname1 and 3 entries are returned. For the filter/facet myname2, filter_max_value_count is explicitly set to the value 5, therefore 5 entries are returned here.
Code
{
"facets": [
{
"formats": [
"HTML"
],
"name": "myname1"
},
{
"formats": [
"HTML"
],
"name": "myname2",
"filter_max_value_count": 5
}
],
"query": {
"unparsed": "mindbreeze"
}
}
Result
{
"search_request": {
"query": {
"unparsed": "mindbreeze"
},
"facets": [
{
"name": "myname1",
"formats": [
"HTML"
]
},
{
"name": "myname2",
"formats": [
"HTML"
],
"filter_max_value_count": 5
}
],
"user_context": {}
}
"name": "unnamed",
"estimated_count": 254,
"facets": [
{
"id": "myname1",
"name": "myname1",
"entries": [
{
"html": "Case Studies",
"count": 2,
"query_expr": {
"label": "myname1",
"regex": "^\\QCase Studies\\E$",
"description": "Case Studies",
"id": "Case Studies",
"value": {
"str": "Case Studies"
}
},
"value": {
"str": "Case Studies"
}
},
{
"html": "Developer",
"count": 2,
"query_expr": {
"label": "myname1",
"regex": "^\\QDeveloper\\E$",
"description": "Developer",
"id": "Developer",
"value": {
"str": "Developer"
}
},
"value": {
"str": "Developer"
}
},
{
"html": "Management",
"count": 2,
"query_expr": {
"label": "myname1",
"regex": "^\\QManagement\\E$",
"description": "Management",
"id": "Management",
"value": {
"str": "Management"
}
},
"value": {
"str": "Management"
}
}
],
"order_criteria": "COUNT",
"order_direction": "DESCENDING",
"total_value_count": 254,
"distinct_value_count": 226,
"entries_truncated": true,
"count_filtered_facet_values": true,
"incomplete": false
},
{
"id": "myname2",
"name": "myname2",
"entries": [
{
"html": "Basic Indexing",
"count": 2,
"query_expr": {
"label": "myname2",
"regex": "^\\QBasic Indexing\\E$",
"description": "Basic Indexing",
"id": "Basic Indexing",
"value": {
"str": "Basic Indexing"
}
},
"value": {
"str": "Basic Indexing"
}
},
{
"html": "Case Studies",
"count": 2,
"query_expr": {
"label": "myname2",
"regex": "^\\QCase Studies\\E$",
"description": "Case Studies",
"id": "Case Studies",
"value": {
"str": "Case Studies"
}
},
"value": {
"str": "Case Studies"
}
},
{
"html": "Developer",
"count": 2,
"query_expr": {
"label": "myname2",
"regex": "^\\QDeveloper\\E$",
"description": "Developer",
"id": "Developer",
"value": {
"str": "Developer"
}
},
"value": {
"str": "Developer"
}
},
{
"html": "GSA Replacement",
"count": 2,
"query_expr": {
"label": "myname2",
"regex": "^\\QGSA Replacement\\E$",
"description": "GSA Replacement",
"id": "GSA Replacement",
"value": {
"str": "GSA Replacement"
}
},
"value": {
"str": "GSA Replacement"
}
},
{
"html": "Management",
"count": 2,
"query_expr": {
"label": "myname2",
"regex": "^\\QManagement\\E$",
"description": "Management",
"id": "Management",
"value": {
"str": "Management"
}
},
"value": {
"str": "Management"
}
}
],
"order_criteria": "COUNT",
"order_direction": "DESCENDING",
"total_value_count": 254,
"distinct_value_count": 226,
"entries_truncated": true,
"count_filtered_facet_values": true,
"incomplete": false
}
]
}
Setting filters in a request
In addition, it is possible to set filters in the request. This results in the same behavior as if you had selected a filter value in the client to limit the search. To do this, you must set the query expression of the selected filter value in the request, as in the example below. Please note that you can also use multiple query expressions in the form of a list as a request in order to select several filter values at the same time.
Code
{
"user":{
"query": {
"unparsed": "mindbreeze"
},"constraints": [
{
"label": "extension",
"filter_base": [
{ "label": "extension",
"regex": "^\\Qpng\\E$",
"description": "png",
"id": "png",
"value": {"str": "png"}
},{
"label": "extension",
"regex": "^\\Qpdf\\E$",
"description": "pdf",
"id": "pdf",
"value": {"str": "pdf"}
}
]
},{
"label": "mes:date",
"filter_base": [
{ "and": [
{num: 1514764800000, cmp: "GE", unit: "ms_since_1970"},
{num: 1546300799999, cmp: "LE", unit: "ms_since_1970"}
],
"label": "mes:date",
"description": "2018",
"id": "2018",
"value": {
num: 1514764800000,
unit: "ms_since_1970"
}
}
]
}
]
},
"count": 1,
"properties": [{
"name": "title",
"formats": ["HTML"]
},{
"name": "content",
"formats": ["HTML"]
}],
"facets":[
{
"name":"extension"
"formats":[
"HTML"
]
}
]
}
Result
"resultset": {
"results": [
{
"id": "SAP KMC:Default:/irj/go/km/docs/documents/MarketingPRTestdaten/Vorschlag%20Fotos%20zur%20Verwendung%20FFPR%20_%20Mobile%20Suche/Mindbreeze-Suche%20am%20iPad%20%c2%a9%20Mindbreeze.png:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzM5OjIxNzc=",
"rank_score": 35.896,
"relevance_score": 35.896,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "<em>Mindbreeze</em>-Suche am iPad © <em>Mindbreeze</em>.png"
}
]
}
],
"order": {
"num": 358960
},
"group": {
"str": ""
}
}
Disabling/enabling the counting of filtered values
You can control whether filtered values should be counted using the option count_filtered_facet_values in the search query. If the option is not selected, the default behavior is to use the Mindbreeze InSpire configuration. If not configured otherwise, the filtered values are counted (true). The option in the request overwrites the configuration unconditionally.
Code
{
"user":{
"query": {
"unparsed": "mindbreeze"
},"constraints": [{ "label": "extension","filter_base": [
{"label": "extension", "regex": "^\\Qpng\\E$", "description": "png", "id": "png", "value": {"str": "png"}}]}]
},
"count": 1,
"count_filtered_facet_values": false,
"properties": [{
"name": "title",
"formats": ["HTML"]
},{
"name": "content",
"formats": ["HTML"]
}],
"facets":[
{
"name":"extension"
"formats":[
"HTML"
]
}
]
}
Request Facets as Properties
You can use the request_facest_as_properties option in the request to ensure that properties requested as facets are also requested as properties.This does not affect the documents E2E, but correctly reduces the number of documents in the facets when duplicates are filtered in the response.
Code
{
"count": 5,
"request_facets_as_properties": true,
"properties":[
{
"name":"title"
}
],
"facets":[
{
"name":"mes:date"
},
{
"name":"mes:configuredfacets"
}
],
"user":{
"query":{
"unparsed":"ALL"
}
}
}
Summarize search results
With the field summarize_by you can group and sort results by selectable properties.
Code
{
"query": {
"unparsed": "mindbreeze"
},
"count": 1,
"properties": [{
"name": "title",
"formats": ["HTML"]
}, {
"name": "content",
"formats": ["HTML"]
}
],
"query_context_user_query": "mindbreeze",
"summarize_by": {
"property": "mes:extension",
"orderby": "mes:date",
"order_direction": "ASCENDING",
"aggregated_properties": [{
"name": "countName",
"expr": "count()"
}, {
"name": "sumName",
"expr": "sum(mes:size)"
}
],
"summarize_non_existent": false
}
}
Description of fields
- property: The property by which the results should be groupable.
Example: mes:extension - orderby: The property by which the grouped results should be ordered.
Example: mes:date - order_direction: Whether the results should be ordered in ascending (ASCENDING) or descending (DESCENDING) order.
- aggregated_properties: Grouped results can also be summarised according to aggregated properties.
Note: The results are not changed, but only a new property is made available, which can be inserted at any place in the HTML via Mustache template (e.g.: next to the title).- name: The name of the property. Can be anything, but must be unique.
- expr: The property or method after which the results are summarised:
- count(): Counts or returns the number per grouped result.
- sum(<parameter>): Sums the property (Property) specified in the parameter of all results that are in a group. Only sums of numerical properties are possible.
Example: sum(mes:size): Sums up the file sizes. - avg(<parameter>): Calculates the average of the property specified in the parameter of all results that are in a group. Only averages for numerical properties are possible.
Example: avg(mes:size): Calculates the average of the file sizes. - min(<parameter>): Calculates the smallest value of the property specified in the parameter of all results that are in a group. Only minimum values for numerical properties are possible.
Example: min(mes:size): Calculates the smallest value of the file sizes. - max(<parameter>): Calculates the largest value of the property specified in the parameter of all results that are in a group. Only maximum values for numerical properties are possible.
Example: max(mes:size): Calculates the largest value of the file sizes.
- summarize_non_existent: Whether all other results that do not have the specified property are also combined into a common group.
Sentence Transformer Settings
The NLQA related options answer_count, min_similarity_score and answer_format can be specified in the request.
The answer_count is the maximum number of answers that should be returned in the response.
The min_similarity_score option defines the minimum score that an answer must have. The score is a value between 0 and 1 and the higher the score, the better the answer.
The setting answer_format can be set to either UNFORMATTED_ANSWERS, FORMATTED_ANSWERS or FORMATTED_AND_UNFORMATTED_ANSWERS:
- UNFORMATTED_ANSWERS (default): The texts in the answers fields (text.text, text.context_before and text.context_after) are returned as plain text.
- FORMATTED_ANSWERS: The texts in the answers field are returned with HTML formatting to reproduce the structure of the original document.
- FORMATTED_AND_UNFORMATTED_ANSWERS: The texts in the answers field are returned as plain text. A separate list of formatted_answers is generated that contains text with HTML formatting.
"count":5,
"answer_count":5,
"min_similarity_score": 0.7,
"answer_format": "FORMATTED_ANSWERS",
"user":{
"query":{
"similar":"How many connectors does Mindbreez have?"
}
}
}
External Contextualization Settings
External contextualization can be deactivated with the setting disable_external_contextualisation.
This setting is not set by default, which means that the client service setting “Disable External Contextualisation” is effective:
{
"count":5,
"disable_external_contextualization": true
"user":{
"query":{
"similar":"Wieviele Konnektoren stellt Mindbreeze zur verfügung?"
}
}
}
For more information about this client service setting, see Documentation - Mindbreeze InSpire - Disable External Contextualization.
Performance and other parameters for requests
Language
The language can be specified
This makes it possible to obtain metadata labels that are already translated:
{
"query": {
"unparsed": "mindbreeze"
},
"count": 1,
"properties": [{
"name": "title",
"formats": ["VALUE","HTML"]
},{
"name": "content",
"formats": ["VALUE","HTML"]
}],
"user_context":{
"locale":"de"
}
}
Result
"resultset": {
"results": [
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/de/inspire-training-feb2017:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjM1MTA=",
"rank_score": 42.5445,
"relevance_score": 42.5445,
"properties": [
{
"id": "title",
"name": "Titel",
"data": [
{
"html": "<em>Mindbreeze</em> InSpire Training",
"value": {
"str": "Mindbreeze InSpire Training"
}
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "<em>Mindbreeze</em> InSpire Training\nDauer...Februar 2017\nOrt: <em>Mindbreeze</em> Academy, Honauerstraße 2...direkt von den <em>Mindbreeze</em>-Experten alles über...wichtigsten Neuerungen von <em>Mindbreeze</em> InSpire. Wir freuen...der Welt von <em>Mindbreeze</em> vertraut gemacht. Die",
"value": {
"str": ""
}
}
]
}
],
"order": {
"num": 425445
},
"group": {
"str": ""
}
}
Task ID
The task ID can be set if the searches take place in the same session. This will stop currently ongoing searches for the current user and only run the last one. If, therefore, more than one search is executed at the same time using the same task ID, all except the last one will be cancelled and the latest run search will be executed.
This can be used to optimize performance in multi-user environments. Best practice: Each session of a Insight App, each open search window should have its own unique task ID.
{
"query": {
"unparsed": "mindbreeze"
},
"count": 1,
"properties": [{
"name": "title",
"formats": ["VALUE","HTML"]
},{
"name": "content",
"formats": ["VALUE","HTML"]
}],
"task_id":"<guid>"
}
Hiding the available properties and facets for the results
When you activate the option exclude_available_properties_and_facets, only the properties/facets that are also specified as properties with value in the call are returned in the response. In our example, all other properties − except for titles and content − are no longer exported when this option is active. If the option is not set, it is automatically false.
Example:
{
"query": {
"unparsed": "mindbreeze"
},
"count": 1,
"properties": [{
"name": "title",
"formats": ["VALUE","HTML"]
},{
"name": "content",
"formats": ["VALUE","HTML"]
}],
"exclude_available_properties_and_facets":true
}
"exclude_available_properties_and_facets": false
…
"resultset": {
"results": [
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/de/inspire-training-feb2017:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjM1MTA=",
"rank_score": 42.5445,
"relevance_score": 42.5445,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "<em>Mindbreeze</em> InSpire Training",
"value": {
"str": "Mindbreeze InSpire Training"
}
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "<em>Mindbreeze</em> InSpire Training\nDauer...Februar 2017\nOrt: <em>Mindbreeze</em> Academy, Honauerstraße 2...direkt von den <em>Mindbreeze</em>-Experten alles über...wichtigsten Neuerungen von <em>Mindbreeze</em> InSpire. Wir freuen...der Welt von <em>Mindbreeze</em> vertraut gemacht. Die",
"value": {
"str": ""
}
}
]
}
],
"order": {
"num": 425445
},
"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"
},
{
"name": "publisher",
"localized_name": "Company"
},
{
"name": "createdby",
"localized_name": "Created"
},
{
"name": "extension",
"localized_name": "Extension"
},
{
"name": "language",
"localized_name": "Language"
},
{
"name": "modifiedby",
"localized_name": "Modified"
},
{
"name": "ownername",
"localized_name": "Owner"
},
{
"name": "path",
"localized_name": "Path"
},
{
"name": "Presentation-Format",
"localized_name": "Presentation format"
},
{
"name": "parent",
"localized_name": "Room"
},
{
"name": "Content-Status",
"localized_name": "Status"
},
{
"name": "breadcrumbs",
"localized_name": "Tag"
}
],
"show_query_spelling_alternatives": false,
"order_direction_available": true
}
"exclude_available_properties_and_facets": true
…
"resultset": {
"results": [
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/de/inspire-training-feb2017:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjM1MTA=",
"rank_score": 42.5445,
"relevance_score": 42.5445,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "<em>Mindbreeze</em> InSpire Training",
"value": {
"str": "Mindbreeze InSpire Training"
}
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "<em>Mindbreeze</em> InSpire Training\nDauer...Februar 2017\nOrt: <em>Mindbreeze</em> Academy, Honauerstraße 2...direkt von den <em>Mindbreeze</em>-Experten alles über...wichtigsten Neuerungen von <em>Mindbreeze</em> InSpire. Wir freuen...der Welt von <em>Mindbreeze</em> vertraut gemacht. Die",
"value": {
"str": ""
}
}
]
}
],
"order": {
"num": 425445
},
"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=="
}
}
]
},
"show_query_spelling_alternatives": false,
"order_direction_available": true
}
Sorting
Explanation
The API also allows the returned results to be sorted by a specified metadata. orderby contains the metadata by which the results are sorted. order_direction (ASCENDING, DESCENDING) determines the order. In our example, we search for “mindbreeze” and the results are sorted by mes:date (default date) (ascending). From the results, only the title and content of the results are returned as HTML. Only the first five results are returned. The default values are mes:relevance and DESCENDING. The search response contains a list of all metadata available for sorting.
Code
{
"query": {
"unparsed": "mindbreeze"
},
"count": 5,
"orderby": "mes:date",
"order_direction": "ASCENDING",
"properties": [{
"name": "title",
"formats": ["HTML"]
},{
"name": "content",
"formats": ["HTML"]
}]
}
Result
"resultset": {
"results": [
{
"id": "Atlassian Confluence:confluence:https://demo.mindbreeze.com/confluence/download/attachments/1343604/Monitor_Working_Wikily_2%200.pdf?api=v2:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzM4Ojgz",
"rank_score": 340231.0284,
"relevance_score": 0,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "Monitor_Working_Wikily_2 0.pdf"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "Social Change with a Network Mindset\r\nWORKING\r\nWIKILY2.0 Created by the\r\nMonitor Institute\r\nwww.monitorinsitute.com\r\nThis work is licensed under the Creative Commons Attribution Share Alike 3.0 Unported License.\r\nIt’s probably safe to say by now that we all know about web 2.0. We’ve read a blog. \r\nWe’ve looked something up on Wikipedia. We’ve created a Facebook profile and started collecting friends. We may have even “tweeted.” The tools are now accessible to the \r\npoint where, f..."
}
]
}
],
"order": {
"num": 3402310284
},
"group": {
"str": ""
}
},
{
"id": "Atlassian Confluence:confluence:https://demo.mindbreeze.com/confluence/download/attachments/1343604/Wiki-based%20Portfolio%20Mgmt_DMR_Nr3_Tempich_2009_D.pdf?api=v2:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzM4OjE4NA==",
"rank_score": 340231.0491,
"relevance_score": 0,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "Wiki-based Portfolio Mgmt_DMR_Nr3_Tempich_2009_D.pdf"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "Strategy\r\n29 Detecon Management Report • 3 / 2009\r\n ie Steuerung von komplexen Produkt- oder Geschäftsfeldportfolios mit Hilfe des Portfolio-Management hat sich in den \r\nletzten Jahren in vielen Großkonzernen etabliert. Auch wir nutzen die Portfolio-Methode in der Analysephase vieler unserer \r\nProjekte, um schnell Transparenz über die Wettbewerbssituation, \r\ntechnische Anforderungen, Prozesse und andere Analyseobjekte \r\nzu erlangen. Bei der Anwendung von Portfolio-Management \r\nkommt es ..."
}
]
}
],
"order": {
"num": 3402310491
},
"group": {
"str": ""
}
},
…
Grouping
Explanation
In this example, the term “mindbreeze” is searched, and the search is grouped according to the metadata extension. This can be defined using groupby.property. From the results, only the title and content of the results are returned as HTML. Only the first five results are returned. The results contain the grouping value in group. The results are sorted according to mes:date.
Code
{
"query": {
"unparsed": "mindbreeze"
},
"count": 5,
"orderby": "mes:date",
"groupby": {
"property": "extension"
},
"properties": [{
"name": "title",
"formats": ["HTML"]
},{
"name": "content",
"formats": ["HTML"]
}]
}
Result
"resultset": {
"results": [
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/enterprise-search-appliance:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjQwNjE=",
"rank_score": 362366.644,
"relevance_score": 0,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "The Enterprise Search Appliance"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "all their knowledge.\n<em>Mindbreeze</em> InSpire can help...Enterprise Search Appliance\n<em>Mindbreeze</em> analyzes both structured...the individual contents.\n<em>Mindbreeze</em> InSpire comes to...GSA configuration into <em>Mindbreeze</em> InSpire <em>Mindbreeze</em> InSpire supports all"
}
]
}
],
"order": {
"num": 3623666440
},
"group": {
"str": "html"
}
},
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/de/enterprise-search-appliance:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjQwNjI=",
"rank_score": 362366.6438,
"relevance_score": 0,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "Die Enterprise Search Appliance"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "agieren zu können.\n<em>Mindbreeze</em> InSpire hilft Ihnen...Enterprise Search Appliance\n<em>Mindbreeze</em> InSpire kommt zu...Hardware samt Suchsoftware. \n<em>Mindbreeze</em> analysiert strukturierte und...GSA-Konfiguration in <em>Mindbreeze</em> InSpire <em>Mindbreeze</em> InSpire unterstützt alle"
}
]
}
],
"order": {
"num": 3623666438
},
"group": {
"str": "html"
}
},
…
Time zone
Explanation
It is also possible to retrieve results taking the time zone into consideration. 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.
In our example, we’re searching for “mindbreeze” and Central European Summer Time is used. From the results, only the date and content of the results are returned as HTML. Only the first five results are returned. The results are sorted according to mes:date.
Code
{
"query": {
"unparsed": "mindbreeze"
},
"count": 5,
"orderby": "mes:date",
"user_context": {
"utc_time_zone_differential_in_seconds": 7200
},
"properties": [{
"name": "mes:date",
"formats": ["HTML"]
},{
"name": "content",
"formats": ["HTML"]
}]
}
Result
Without time zone
"resultset": {
"results": [
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/enterprise-search-appliance:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjQwNjE=",
"rank_score": 362366.644,
"relevance_score": 0,
"properties": [
{
"id": "mes:date",
"name": "Date",
"data": [
{
"html": "10/11/16 10:46 AM"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "all their knowledge.\n<em>Mindbreeze</em> InSpire can help...Enterprise Search Appliance\n<em>Mindbreeze</em> analyzes both structured...the individual contents.\n<em>Mindbreeze</em> InSpire comes to...GSA configuration into <em>Mindbreeze</em> InSpire <em>Mindbreeze</em> InSpire supports all"
}
]
}
],
"order": {
"num": 3623666440
},
"group": {
"str": ""
}
},
With time zone
"resultset": {
"results": [
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/enterprise-search-appliance:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjQwNjE=",
"rank_score": 362366.644,
"relevance_score": 0,
"properties": [
{
"id": "mes:date",
"name": "Date",
"data": [
{
"html": "10/11/16 12:46 PM"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "all their knowledge.\n<em>Mindbreeze</em> InSpire can help...Enterprise Search Appliance\n<em>Mindbreeze</em> analyzes both structured...the individual contents.\n<em>Mindbreeze</em> InSpire comes to...GSA configuration into <em>Mindbreeze</em> InSpire <em>Mindbreeze</em> InSpire supports all"
}
]
}
],
"order": {
"num": 3623666440
},
"group": {
"str": ""
}
},
…
Timeout
Explanation
A timeout can also be defined for the search. If this timeout is exceeded, the search is aborted. timeout_in_seconds defines the maximum duration of the search. The results are sorted according to mes:date.
Code
{
"query": {
"unparsed": "mindbreeze"
},
"count": 5,
"orderby": "mes:date",
"timeout_in_seconds": 1,
"properties": [{
"name": "title",
"formats": ["HTML"]
},{
"name": "content",
"formats": ["HTML"]
}]
}
Specifying the length of an extract of content
Explanation
The parameter content_sample_length specifies the maximum length in characters of the body of the sample text for results. If this is exceeded, the text is truncated at the limit. The default value is set to 100 characters.
Code
{
"query": {
"unparsed": "mindbreeze"
},
"count": 5,
"orderby": "mes:date",
"content_sample_length": 2,
"properties": [{
"name": "title",
"formats": ["HTML"]
},{
"name": "content",
"formats": ["HTML"]
}]
}
Without limit
"resultset": {
"results": [
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/enterprise-search-appliance:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjQwNjE=",
"rank_score": 362366.644,
"relevance_score": 0,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "The Enterprise Search Appliance"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "all their knowledge.\n<em>Mindbreeze</em> InSpire can help...Enterprise Search Appliance\n<em>Mindbreeze</em> analyzes both structured...the individual contents.\n<em>Mindbreeze</em> InSpire comes to...GSA configuration into <em>Mindbreeze</em> InSpire <em>Mindbreeze</em> InSpire supports all"
}
]
}
],
"order": {
"num": 3623666440
},
"group": {
"str": ""
}
},
…
Relevance and Boosting
There is a white paper with more detailed information about relevance. This section deals with the structure.
Relevance factors
With the property relevance_factors, the individual relevance factors can be set, such as the timeliness of the hit, the proximity of hits to each other in the document, etc. The total weighting of all the factors is determined and then the individual parameters are relatively weighted.
Recency | 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 |
Weighting of the document boostings | |
answer_doc_boost_exponent | Weighting of the document boostings for Answers (NLQA) |
- In our example, we search the term “mindbreeze” and the first five results are returned. In addition, the defined boosting is applied to the query. From the results, only the title and content of the results are returned as HTML. Only the first five results are returned.
Boostings
The property boostings can be used to set boostings on properties, metadata or documents.
The following boosting affects the metadata url, hits in this property are weighted twice compared to other metadata/properties. The special property content can be used to weight the content of the hit.
"boostings": [{
"id": "url",
"factor": 2
}]
In addition to boosting based on the id, a query_expr can also be stored. The documents for which this expression applies are boosted. In the example below, all documents whose extension property has the value png are boosted by 20%.
"boostings": [{
"id": "extension_png_boosting",
"factor": 1.2
"query_expr": {
"label": "extension",
"regex": "^\\Qpng\\E$"
}
}]
Another possibility is to define boosting factors based on metadata. For this purpose, expressions can be defined in property_expr_factor using the Mindbreeze Property Expression Language.
In the example below, all documents are boosted by a factor of 5, for which the metadata is_critical has the value "true". It is recommended to specify the maximum boost factor using max_factor. Note that the metadata used in property_expr_factor must be aggregatable.
"boostings": [{
"property_expr_factor": "is_critical && float(5) || float(1)",
"max_factor": 5.0
}]
Additive Document Boosting
The additive Document Boosting can be activated using the property enable_additive_boosting. If additive Document Boosting is deactivated (default setting), only the one with the highest value is active for multiple applicable Document Boostings (boosting with a query_expr). If additive document boosting is activated, all applicable document boostings of a document are added (negative values are also possible here).
In the example below, the option enable_additive_boosting png now boosts images from the Web data source 1.3 times, all other png images 1.2 times and the remaining content from the Web source 1.1 times, all other hits 1.0 times. If this option was not activated, all images would be weighted with 1.2, regardless of whether they are from the Web data source or not.
{
"query": {
"unparsed": "mindbreeze"
},
"count": 5,
"enable_additive_boosting": true,
"boostings": [{
"id": "extension_png_boosting",
"factor": 1.2
"query_expr": {
"label": "extension",
"regex": "^\\Qpng\\E$"
}
}, {
"id": "category_Web_boosting",
"factor": 1.1
"query_expr": {
"label": "category",
"regex": "^\\QWeb\\E$"
}
}
]
}
Additive Zone Boosting (experimental)
Additive Zone Boostings can be activated using the property enable_additive_zone_boosting. If additive Zone Boostings are deactivated (default setting), only the zone with the highest applicable boost factor is considered. If additive Zone Boostings are activated, all matching zones are considered for computing the boosting. Negative boostings are also possible here, with factors less than 1.
In the example below, documents containing “mindbreeze” in the title are boosted 1.25 times, documents containing “mindbreeze” in the metadatum keywords are boosted 1.1 times. If enable_additive_zone_boosting is activated, documents containing “mindbreeze” both in the title and the keywords will be boosted 1.35 times. If the option is not activated, they will be boosted 1.25 times.
{
"query": {
"unparsed": "mindbreeze"
},
"count": 5,
"enable_additive_zone_boosting": true,
"boostings": [{
"id": "title",
"factor": 1.25
},{
"id": "keywords",
"factor": 1.1
}
}
]
}
Code:
{
"query": {
"unparsed": "mindbreeze"
},
"count": 5,
"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
}
,
"properties": [{
"name": "title",
"formats": ["HTML"]
},{
"name": "content",
"formats": ["HTML"]
}]
}
Result:
Without boosting
"resultset": {
"results": [
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/de/inspire-training-feb2017:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjM1MTA=",
"rank_score": 42.5325,
"relevance_score": 42.5325,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "<em>Mindbreeze</em> InSpire Training"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "<em>Mindbreeze</em> InSpire Training\nDauer...Februar 2017\nOrt: <em>Mindbreeze</em> Academy, Honauerstraße 2...direkt von den <em>Mindbreeze</em>-Experten alles über...wichtigsten Neuerungen von <em>Mindbreeze</em> InSpire. Wir freuen...der Welt von <em>Mindbreeze</em> vertraut gemacht. Die"
}
]
}
],
"order": {
"num": 425325
},
"group": {
"str": ""
}
},
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/de/inspire-training-nov2017:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjM1MTY=",
"rank_score": 42.5325,
"relevance_score": 42.5325,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "<em>Mindbreeze</em> InSpire Training"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "<em>Mindbreeze</em> InSpire Training\nDauer...November 2017\nOrt: <em>Mindbreeze</em> Academy, Honauerstraße 2...direkt von den <em>Mindbreeze</em>-Experten alles über...wichtigsten Neuerungen von <em>Mindbreeze</em> InSpire. Wir freuen...der Welt von <em>Mindbreeze</em> vertraut gemacht. Die"
}
]
}
],
"order": {
"num": 425325
},
"group": {
"str": ""
}
},
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/de/inspire-training-nov2016:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjM1MTg=",
"rank_score": 42.5325,
"relevance_score": 42.5325,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "<em>Mindbreeze</em> InSpire Training"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "<em>Mindbreeze</em> InSpire Training\nDauer...November 2016\nOrt: <em>Mindbreeze</em> Academy, Honauerstraße 2...direkt von den <em>Mindbreeze</em>-Experten alles über...wichtigsten Neuerungen von <em>Mindbreeze</em> InSpire. Wir freuen...der Welt von <em>Mindbreeze</em> vertraut gemacht. Die"
}
]
}
],
"order": {
"num": 425325
},
"group": {
"str": ""
}
},
…
With boosting
"resultset": {
"results": [
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/de/developer/basic-indexing:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjM5ODg=",
"rank_score": 44.989,
"relevance_score": 44.989,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "Basic Indexing"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "von Objekten an <em>Mindbreeze</em>. Sie lernen die...müssen.\nObjekte an <em>Mindbreeze</em> senden Ein Objekt...Facetten \nObjekte an <em>Mindbreeze</em> senden\nUm Objekte...Ihrer Datenquelle an <em>Mindbreeze</em> schicken können. Es...kümmert sich darum?\n<em>Mindbreeze</em> verwendet Crawler, um"
}
]
}
],
"order": {
"num": 449890
},
"group": {
"str": ""
}
},
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/developer/basic-indexing:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjM5OTI=",
"rank_score": 44.9465,
"relevance_score": 44.9465,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "Basic Indexing"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "data source to <em>Mindbreeze</em>. You will learn...Send objects to <em>Mindbreeze</em> Send an object Send...Send objects to <em>Mindbreeze</em>\nIn order to be...data source to <em>Mindbreeze</em>. It’s very easy...care of it?\n<em>Mindbreeze</em> uses crawlers to"
}
]
}
],
"order": {
"num": 449465
},
"group": {
"str": ""
}
},
{
"id": "Web:wwwmindbreezecom:https://www.mindbreeze.com/de/inspire-training-feb2017:",
"location": "aHR0cHM6Ly9pbnNwaXJlcHJvZC5pbnNwaXJlLm1pbmRicmVlemUuY29tOjIzMzMxOjM1MTA=",
"rank_score": 43.5325,
"relevance_score": 43.5325,
"properties": [
{
"id": "title",
"name": "Title",
"data": [
{
"html": "<em>Mindbreeze</em> InSpire Training"
}
]
},
{
"id": "content",
"name": "content",
"data": [
{
"html": "<em>Mindbreeze</em> InSpire Training\nDauer...Februar 2017\nOrt: <em>Mindbreeze</em> Academy, Honauerstraße 2...direkt von den <em>Mindbreeze</em>-Experten alles über...wichtigsten Neuerungen von <em>Mindbreeze</em> InSpire. Wir freuen...der Welt von <em>Mindbreeze</em> vertraut gemacht. Die"
}
]
}
],
"order": {
"num": 435325
},
"group": {
"str": ""
}
},
…