Appendix - Search API Parameters

sl or logic

• String, monovalued.
• Must reference a valid logic, defined in the search logics list.

Example: print the query ast and not the ellql

q=job&sl=sl0
q=job&logic=sl0

st or target

• String, monovalued.
• Must reference a valid search target

Example: print the query ast and not the ellql

q=job&st=st0
q=job&target=st0

c or context

The context contains the encoded version of previous arguments to chain queries.

d or debug

Turns on various debugging flags for this query.

Value is a comma-separated list of the following parameters:

d=ast,-ellql

d=all,-fh

d=all,-context

hit_infos; hit_info, hi

Puts additional info in the hit to debug the ranking. The following info is supported:

q=vacation&hi=ast
q=vacation&hi=ast,rankings

applicationId

In V6.x, you can create multiple applications using the Mashup Builder. This parameter is the Mashup application ID passed by the API client.

To trigger the Business Processor at runtime, you have to pass the applicationId parameter and optionally, the stagingMode parameter:

Examples:

• http://SEARCH_API_HOST:SEARCH_API_PORT/search-api/search?q=test&applicationId=default&stagingMode=false - The Business Processor uses the "default" application configuration and precompiled resources.
• http://SEARCH_API_HOST:SEARCH_API_PORT/search-api/search?q=test&applicationId=default&stagingMode=true - The Business Processor uses the "default" application configuration and compile resources at query-time.
• http://SEARCH_API_HOST:SEARCH_API_PORT/search-api/search?q=test&applicationId=default - The Business Processor will use the "default" application configuration and precompiled resources.
• http://SEARCH_API_HOST:SEARCH_API_PORT/search-api/search?q=test - The Business Processor is not triggered.

Checkpoints

The list of checkpoint values to retrieve on each slice, stored in the answer's slice info.

Value is a comma-separated list of checkpoint names.

Origin

This parameter has no impact on query treatment. However, it is logged in the search.csv file and can help you identify the origin of the query, when you analyze user queries using the search-reporting reporter with a CSV publisher. It is useful for better traceability and debugging.

s or sort

Sort is declared through several parameters:

Example: sort alphabetically by region and then by price

s=asc(document_region),desc(document_price)

Example: sort alphabetically by increasing price, decreasing score and then by increasing file size. 'myprice' and 'myscore' are '[sort id]' [sort id] can not contain any space, or comma, or closing parenthesis, nor point. If such characters are required, use the expanded syntax.

s=asc(myprice),desc(myscore),asc(document_file_size)
s.myprice.expr=price-discount
s.myscore.expr=@term.score*@proximity*#round(document_double,4)

Example: sort by color index defined on 4 bits in the index field document_bitfield.

s=asc(color)
s.color.expr=document_bitfield
s.color.lsb=12
s.color.msb=15

is the same as: s=asc(document_bitfield[12:15])

The following syntax is also supported for backward compatibility. It allows only mono field sort.

• s=field - Sort descending on field.
• s=-field - Sort ascending on field.
• s=field[lsb,msb] - Sort descending on field, restricted to a given bitrange.
• s=-field[lsb,msb] - Sort ascending on field, restricted to a given bitrange.

Group

Theses parameters control the GroupBy feature.

By default, a group pass has a single group dimension defined with expr set to [group identifier]. [group id] and [criterion id] can neither contain comma, nor point. If such characters are required in the expression, use the expanded syntax.

Example: Keep one document for each state. The best one is selected according to the ranking sort, the others are discarded.

group=document_region

Example: Keep the five best documents for each state.

group=document_region
group.document_region.topn=5

Example: Same as previous, but uses a label to identify the group rather than the field name.

group=byRegion
group.byRegion.by=document_state
group.byRegion.topn=5

Example: Keep the best noted hit per region, sort regions per hit count, and display the count. This example relies on the constant virtual expression 1.

group=document_region
group.document_region.aggregation=1
group.document_region.aggregation.1.function=SUM
group.document_region.sort=desc(document_note)
sort=desc(1)
add_hit_meta=1

is the same as:

add_virtual_field=count:1
group=document_region
group.document_region.aggregation=count
group.document_region.aggregation.count.function=SUM
group.document_region.sort=desc(document_note)
sort=desc(count)
add_hit_meta=count

Example: Keep no more than five hit per region, and no more that eight times the same product. This configuration creates two independent collapsing passes. The result set may contain fewer than 5 hits per region because document_product_name removes hits of the groups made by document_region pass.

group=document_region,document_product_name
group.document_region.topn=5
group.document_product_name.topn=8

Example: Keep one record for each firstname, lastname pair, select most recently updated hit, and get the average note in document_note and the total expense in total_expense. Finally results are sorted alphabetically.

group=byPerson
group.byPerson.by=document_firstname,document_lastname
group.byPerson.s=desc(document_lastupdatedate)
group.byPerson.aggregation=document_note,document_price
group.byPerson.aggregation.document_note.function=AVG
group.byPerson.aggregation.document_price.function=SUM
group.byPerson.aggregation.document_price.aggregationField=total_expense
sort=asc(document_lastname),asc(document_fisrtname)
add_hit_meta=document_note
add_hit_meta=total_expense

Collapsing (DEPRECATED)

collapsing parameters are supported for backward compatibility. Prefer group parameters.

Example: Keep one document for each state. The best one is selected according to the ranking sort, the others are discarded.

collapsing=document_region

Example: Keep the five best documents for each state.

collapsing=document_region
collapsing.document_region.nbhits=5

Example: Same as previous but uses a label to identify the group rather than the field name.

collapsing=byRegion
collapsing.byRegion.expr=document_state
collapsing.byRegion.nbhits=5

Example: Keep one hit per region, sort regions per hit count, and display the count. This example relies on the constant virtual expression 1.

collapsing=document_region
collapsing.document_region.action.1=add
sort=desc(1)
add_hit_meta=1

Example: Keep no more than five hits per region, and no more that eight times the same product. This configuration creates two independent collapsing passes. The result set may contain fewer than 5 hits per region because document_product_name remove hits of the groups made by document_region pass.

collapsing=document_region,document_product_name
collapsing.document_region.nbhits=5
collapsing.document_product_name.nbhits=8

q or Query

• string in UQL format
• Parameter name can be in the form q.X to define a named query.

Example:

q=olympic games
query=olympic games

eq or ellql_query

• string in ELLQL format
• Parameter name can be in the form eq.X to define a named query.

Example: search for olympic games in text field

eq=#alphanum(text, "olympic games")

qt or query_template

• String, in the form of an ELLQL tree, defining how to combine the named queries
• Default value: #and(#query(_default_) #query(restriction) #query(security) #query(refine))
• If a named query does not exist, it is replaced by a !NoOp() node and therefore ignored.

Security, enforce_security

• Adds a security token, multivalued.
• Used to increase the auto-built disjunction in the "security" named query.
• By default, security tokens generate category lookups on the "security" field.
• enforce_security=true|false globally enables or disables security.

Example: search for word "secured" in text field with security enabled and security token provided

q=secured&enforce_security=true&security=unix:user:10125

l or lang

• string, monovalued
• The global query ISO language.
• This parameter does not restrict searches to documents in this language. It only controls the language used for computing linguistic expansions, spell checking, and summarization.

Example: search for word "vacation" in text field in English language

q=vacation&l=en

r or refine

• Adds a refinement.
• The combination of refines which creates a named query called "refines".

Example: search for word "vacation" in text field and refine on source category "corpus"

q=vacation&r=f/source/corpus

cr or cancel_refine

Cancels a refinement completely.

Example: search for word "vacation" in text field, refine on source category "corpus" and cancel this refine

q=vacation&r=f/source/corpus&cr=f/source/corpus

zr or zap_refine

Removes a refinement and refines on the father, if applicable. For example, if we have refinement on "Top/MyPath/A/B/C", zapping this refinement replaces it with a refinement on "Top/MyPath/A/B"

Example: search for word "vacation" in text field, refine on source category "corpus" and zap this refine.

q=vacation&r=f/source/corpus&zr=f/source/corpus/english

handle_unknown_refine_as_false

If true, when a r=f/unknownfacet/refine is specified, returns 0 results rather than an error. Default: false

dp or default_prefix

Sets the default prefix handler. The default value is the one specified in the search logic. Can be restricted to a particular named query using dp.NAMED_QUERY_NAME or default_prefix.NAMED_QUERY_NAME.

Example: search for word "vacation" and set default prefix handler to "title", so "vacation" is searched in the title field.

q=vacation&dp=title

qec,query_expansion_config

Sets the QueryExpansionConfig for a given prefix.

The argument name can be specified as:

The argument value (SPEC) is specified as a QEC specification.

pal or patterns_all_languages

Sets whether pattern expansions are performed in all languages (Boolean parameter).

Limits

Defines search limits. This parameter is specified as a KV Map.

The basic keys are:

• max_fetched_hits
• max_fetched_hits_per_slice
• max_query_time
• max_total_time
• hits_sampling

Advanced keys are:

• max_kept_hits
• main_heap_flush_interval
• slice_heap_flush_interval
• interrupt_grace_delay
• full_grace_delay

Detailed documentation of these parameters can be found in SearchLogic / LimitsConfig in XML Configuration Reference

Example: Override timeout and limits

limits=max_total_time:0&limits=max_query_time:n&limits=max_fetched_hits_per_slice:0

Timeout

Shortcut for the limits parameter. When you want to set a timeout, unlike the max_total_time parameter, the timeout=X parameter also sets the value of max_query_time parameter.

• timeout=INT - Sets the global timeout. Query timeout is 75% of the global value.
• timeout=INT,INT - Sets the query and global timeouts.

nhits

Shortcut for limits=max_kept_hits:INT

hf or full_hits,nresults

Number of full hits. hf=0 disables full hits fetch.

b or start

First full hit index. For example, to search on the:

• first page: b=0&hf=10
• second page: b=10&hf=10

use_logic_hit_metas

• true/false - (Optional) Removes all metas defined in the search logic. Default is true.
• metaname1,metaname2,metaname3 - Keeps only this list of metas. Be careful they must exist in search logic unless allow_unknown_hit_meta is true.

allow_unknown_hit_meta

Optional: Allows you to set an unknown meta in the list provided in use_logic_hit_metas , which is silently discarded. Default is false.

add_hit_meta

Add a new hit meta to the query result. Use multiple add_hit_meta clauses to add multiple metas. The value is a list of key:value separated by commas:

add_hit_meta=name:bar,index_field:foo,select_values:true,max_values:N

There is a compact syntax for add_hit_meta that supports only index_fields and highlighting:

• name - Name of the index field
• name,hl - Name of the index field, highlight:Boolean

Example: Simplified syntax

add_hit_meta=document_field_name,hl

is the same as: add_hit_meta=index_field:document_field_name,highlight:true

Example: Extracts color and value from the dynamic property named document_dynamic_field.

add_hit_meta=dynamic_field:document_dynamic_field,name:color&
add_hit_meta=dynamic_field:document_dynamic_field,name:value

Example: You could also extract color from the dynamic property named document_dynamic_field and output its value in meta named property using a virtual expression:

add_hit_meta=dynamic_field:document_dynamic_field,name:property,context_name:color

To use a virtual expression in a hit meta:

• hit_meta.name.expr=expr - where name can contain any character, and expr is a virtual expression.

Add meta specific operation:

• First, you have to define the type of your operation, using the following syntax: (add_)hit_meta.META_NAME.operation.OPERATION_ID.type
• Then, you can associate properties to a given operation: (add_)hit_meta.META_NAME.operation.OPERATION_ID.property.OPERATION_PROPERTY

The following tables list available properties associated by type:

Example: Adds a meta hello from the field document_polite with a truncate processor named truncate_hello with max_length=10, strict=true

add_hit_meta=name:hello,index_field:document_polite&
hit_meta.hello.operation.truncate_hello.type=truncate&
hit_meta.hello.operation.truncate_hello.property.max_length=10&
hit_meta.hello.operation.truncate_hello.property.strict=true

add_hit_metas

Extract all values from a multivalued field. It applies to multi fields (a.k.a. csv fields) and dynamic fields. The value is a key:value list separated by comma.

For dynamic fields only, you can also:

• Select a subset of contexts if you specify match rules (available rules: "exact", "prefix", "suffix", "substring"). You have to use them as key, the associated value being the pattern you are looking for.
  Note: You can associate several rules. In this case, the hit meta is displayed if its name matches at least one rule.
• Specify the name of the meta that receives all the content of the dynamic field. If not set, for each pair key:value stored in the field, a meta named as the key is created.

Simplified syntax when the type of field is not specified multi_field is assumed.

Example: simple syntax

add_hit_metas=document_csv_field

is the same as: add_hit_metas=multi_field:document_csv_field

Example: dynamic field (displays all contexts)

add_hit_metas=dynamic_field:document_dynamic_field

Example: dynamic field with exact match rules (displays toto_first and toto_second but not toto_third)

add_hit_metas=dynamic_field:document_dynamic_field,exact:toto_first,exact:toto_second

Example: dynamic field with prefix rules (displays toto_first and toto_second but not titi_first)

add_hit_metas=dynamic_field:document_dynamic_field,prefix:toto_

Example: dynamic field with name (if dyn_[first:value1 first:value1] and dyn_[second:value2 second:value2] are stored, displays metagroup:value1,value2)

add_hit_metas=dynamic_field:document_dynamic_field,prefix:dyn_,name:metagroup

remove_hit_meta

In the search logic, metas are identified by their names in the HitConfig object. When you remove a meta, this removes all sources and all processors attached to this meta. Value = meta name

add_highlight

Highlights an existing meta. Value = meta name

add_summary

Summarizes an existing meta. Value = meta name

hit_meta_order

Comma-separated list specifying in which order to display metas. Applicable only to CSV output.

All metas not present in the list are displayed after the metas present in the list.

Synthesis

• enabled/disabled
• Defaults to search logic config value.

synthesis_hits

• Number of hits used for category synthesis.
• Defaults to the value in the search logic.

use_logic_facets

Specifies the search logic facets to use and disables all other facets. For the specified facets, the configuration is read in the search logic.

• true - keeps all (default value)
• false - removes all
• facet_id1,facet_id2,...,facet_idN - keeps only this list of facets

remove_facet

One argument: facet_id.

f.* or facet.*

Creates a facet. Facets are specified as multiple parameters, like facet.FACET_ID.key=value where FACET_ID is the facet id (_a-zA-Z0-9).

Example: Standard facet with aggregation - Use this for the default Exalead CloudView index schema, which includes a categories field.

f.common_facet.type=category
f.common_facet.root=Top/ClassProperties/facetmut3
f.common_facet.field=categories
f.common_facet.aggr.total=SUM(doc_int1)

Example: Dedicated facet with aggregation - Use this if you have added another category type field (in this case, stdf3) to your index schema.

f.stdf3.type=category
f.stdf3.root=Top
f.stdf3.field=stdf3
f.stdf3.aggr.total=SUM(doc_int1)

Example:

f.valf3.type=value
f.valf3.vroot=Top/
f.valf3.field=valf3
f.valf3.aggr.total=SUM(doc_int1)

f.cod_ente.type=value
f.cod_ente.vroot=Top/
f.cod_ente.field=cod_ente
f.cod_ente.aggr.total=SUM(anno_ruolo)

Virtual numerical facets are used to organize search results in ranges.

Example: Define custom price ranges and titles for each range

f.price.type=num_explicit
f.price.vroot=Top/Price
f.price.expr=document_dbl1
f.price.range=0,1000,0to1000euros
f.price.range=1000,2000,1000to2000euros
f.price.range=2000,4000,Tooexpensiveforyou

f.mycompany_facet1.type=value
f.mycompany_facet1.vroot=Top/
f.mycompany_facet1.field=mycompany_facet1
            
f.mycompany_facet2.type=value
f.mycompany_facet2.vroot=Top/
f.mycompany_facet2.field=mycompany_facet2
            
f.mat.type=matrix
f.mat.vroot=Top/
f.mat.id2=mycompany_facet1
f.mat.id1=mycompany_facet2
f.mat.aggr.total=SUM(mycompany_int1)
f.mycompany_facet1.max_elements=10
f.mycompany_facet2.max_elements=10

f.heat_consump_apt.type=multi
f.heat_consump_apt.vroot=Top/heat_consump_apt
f.heat_consump_apt1.id=location_code
f.heat_consump_apt2.id=heating_type
f.heat_consump_apt.additional_tree_representation=true
f.heat_consump_apt.aggr.conso=SUM(consumption_statement)
f.heat_consump_apt.in_hits=false

st.* or target.*

Defines a search target. The search target is specified with multiple parameters, like st.TARGET_NAME.key=value or target.TARGET_NAME.key=value where TARGET_NAME is the search target name (_a-zA-Z0-9).

The following keys are supported by all search targets:

• type:string - "local", "simple"
• watch_dog_connect_timeout_ms:int
• watch_dog_read_timeout_ms:int

The local search target supports the following key: build_groups:string

The simple search target requires the definition of target slices. Target slices are specified with multiple parameters, like st.TARGET_NAME.target_slices.TARGET_ID.key=value or target.TARGET_NAME.target_slices.TARGET_ID.key=value where TARGET_NAME is the search target name (_a-zA-Z0-9) and TARGET_ID is a number (0-9). The following keys are supported:

• build_groups:string
• slices:string
• instances:string
• power:int

Examples:

st=my_dynamic_search_target
st.my_dynamic_search_target.type=local

st=my_dynamic_search_target
st.my_dynamic_search_target.type=local
st.my_dynamic_search_target.watch_dog_connect_timeout_ms=1000
st.my_dynamic_search_target.watch_dog_read_timeout_ms=5000
st.my_dynamic_search_target.build_groups=bg0

st=my_dynamic_search_target
st.my_dynamic_search_target.type=simple
st.my_dynamic_search_target.target_slices.0.build_groups=bg0

st=my_dynamic_search_target
st.my_dynamic_search_target.type=simple
st.my_dynamic_search_target.watch_dog_connect_timeout_ms=1000
st.my_dynamic_search_target.watch_dog_read_timeout_ms=5000
st.my_dynamic_search_target.target_slices.0.build_groups=bg0
st.my_dynamic_search_target.target_slices.0.slices=0,1
st.my_dynamic_search_target.target_slices.0.instances=my_instance
st.my_dynamic_search_target.target_slices.0.power=0
st.my_dynamic_search_target.target_slices.1.build_groups=bg1
st.my_dynamic_search_target.target_slices.1.slices=42
st.my_dynamic_search_target.target_slices.1.instances=my_instance
st.my_dynamic_search_target.target_slices.1.power=1

Relevance

Boolean parameter to enable all relevance computation.

Globally disabling relevance computation disables the following features:

• term scoring
• proximity scoring
• sorting
• node properties
• using ranking elements for faceting
• using ranking elements for facet aggregations
• retrieving ranking elements

proximity_max_distance

Maximum distance for proximity matching.

ts (term score)

Sets the term score algorithm. Value must be one of the available algorithms:

• NO_RANKING
• RANK
• TFIDF
• IDF
• RANK_IDF
• RANK_TFIDF
• BM25
• BM25F
• CUSTOM - for this term score algorithm, you must define ts.expr to specify the custom expression.

Streaming

Boolean parameter. If true, all sorts and all limits are ignored.

The answer is NOT cacheable, and is streamed. It is efficient as the synthesis and full hits are computed on-the-fly. It is therefore especially adapted to fetch large results sets without much memory consumption.

In streaming mode, you must iterate over all returned hits, so do not use the getHits() method but getHitsIterator() instead, and read hits using the hasNext and next subcalls.

allow_skip_nhits

Boolean parameter. If true, Exalead CloudView stops counting hits that match the query as soon as possible. The nhits value is allowed to be incorrect.

This advanced parameter must be used for high performance unranked exports without synthesis.

Add an sle

It is possible to add one or more sle to the search URL with the following query parameters:

• set:[path]=[new value] - where path identifies the object field or list element to be replaced by the new value. The previous value is deleted.

  Example: The following example set the performMAX Boolean of the query prefix handler named profiles to true

  sle=set:uQLConfig.queryPrefixHandler[name="profiles"].performMAX=true

• add:[path]=[new list element] - where path identifies the list element before which the new value is inserted. The list element and any subsequent elements are shifted to the right.

  Example: Add a full text prefix handler

  sle=add:uQLConfig.queryPrefixHandler=FullTextPrefixHandler (name="t",indexFields="title",dictionaryName="dict0",matchingMode="normalized")

• remove:[path] - where path identifies the list element to be removed. The element is deleted and any subsequent elements are shifted to the left.

  Example: Remove the first operation of meta named "title"

  sle=remove:hitConfig.meta[name="title"].metaSpecificOperation[0]

Value serialization

*value serialization* depends on the type.

sle Path

The *path* is an element sequence that identifies either an object field or a list element.

The XML representation of the search logic is not representative. There may be missing nodes or case discrepancy.

The path must be built using the javadoc sdk/java-customcode/docs/api/com/exalead/mercury/mami/search/v20/SearchLogic.html.

Object serialization

The *object serialization* is made of two parts: [class](key=value, ...)

• The java class identifier can either be the full qualified name of a java class using . as package separator and '$' for inner classes. For convenience, the simple class name is accepted, and the full name is deduced from the path.

  For example, com.exalead.search.v30.VirtualFieldDefinition or VirtualFieldDefinition

• The initializers is a comma-separated sequence of assignment.

  For example, SnippetOperation(highlightFacetIds="Event,Person",highlightExtraPrefixHandlers="soundslike,spellslike", maxSentenceSegmentLength=210,maxLength=500)

Search Server actions to generate thumbnails

To generate thumbnails, the Search Server:

• Calls the connector fetcher to retrieve the original document from the data source.
• Calculates the thumbnails (it generally uses the convert to do that).
• Sends the document and the calculated thumbnails.

Behavior and tips

• The thumbnail always has the same proportion. If your document does not have the same proportion, a margin will be added to the picture to fill missing gaps.
• The thumbnail is scaled to its MINIMUM value. Let us say you have witdh=90 and height=1200, the width value is the one guiding the downscale.
• Be careful, if your BASEPORT+10 is accessible, anyone can generate thumbnails and if your cache is not properly configured, someone malicious could spam thumbnail generations with huge resolution values.
• The value of the source parameter does not necessarily have to be the same as the connector used to index the document. Remind that the source parameter is required to specify a fetcher to the thumbnails process. For example, you can use a JDBC connector to index your documents, and also create a "dummy" Files connector to generate thumbnails as the JDBC connector does not have a fetcher. This workaround is useful only if you have your own search front end, not if you are using a Mashup UI application.