Caution: This documentation is for eZ Publish legacy, from version 3.x to 6.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

Template fetch functions

Dedicated template fetch functions were introduced in eZ Find 2.0:

For example:

fetch(ezfind, search, hash(<parameters>))

Returns eZ Find search results exposing the powerful features of the backend Solr.

fetch(ezfind, moreLikeThis, hash(<parameters>))

Finds related content with heuristic techniques.

fetch(ezfind, rawSolrRequest, hash(<parameters>))

Allows for “raw” Solr requests (not for normal use, but for example to search “foreign” Solr or Lucene indexes).

Fetch parameters

Review the table for the available fetch parameters. You can click on the parameters for a more elaborate explanation and some examples, or you can scroll down this page and find the explanations and examples of all parameters.

Name

Type

Description

Required

query

String

Search query string

No

offset

Integer

Result offset

No

limit

Integer

Result count limit

No

sort_by

Array

Sort definition

No

facet

Array

Facet query definition

No

filter

Mixed

Search filter, independent from ranking

No

class_id

Mixed

Class ID limitation

No

subtree_array

Array

List of subtree limitations

No

section_id

Integer

Section filter

No

ignore_visibility

Boolean

Visibility filter

No

limitation

Array

Override of the current user's access array to the 'read' function of the 'content' module.

No

as_objects

Boolean

Not implemented yet

No

spell_check

Array

Configure the spell checking behaviour

No

query_handler

String

Which search handler to use

No

Query

The query parameter can contain one or multiple search terms. The query is used to rank and limit the search results. For information about standard Solr query syntax, visit http://wiki.apache.org/solr/SolrQuerySyntax and http://lucene.apache.org/java/docs/queryparsersyntax.html

Example:

fetch( 'ezfind', 'search', hash( query, 'eZ Systems' ) )

Returns:

Returns all documents containing the words “ez” and “systems”.

Example:

fetch( 'ezfind', 'search', hash( query, '”eZ Systems”' ) )

Returns:

Returns all documents containing the term “ez systems”.

Offset

Search result offset. The default value is “0”.

Example:

fetch( 'ezfind', 'search', hash( 'query', 'eZ Systems', 'offset', 20 ) )

Returns:

Returns documents containing the words “ez” and “systems”, starting from the 20th result.

Limit

Search result count limitation. The default value is “10”.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'offset', 0,
    'limit', 25
) )

Returns:

Returns the first 25 documents that contain the words “ez” and “systems”.

Sort_by

The sort_by parameter is used to define the sort order of the search result. It supports the following options:

Key

Description

relevance

Default option. Sorts the result by Solr internal relevancy calculations.

score

Alias to “relevance”

<class attribute>

Content class attribute, following the syntax “<class_identifier>/<class_attribute>[/<sub_structure]”

modified

Modified time

published

Published time

author

Author name

class_name

Content class name

class_id

Content class identifier or content class ID

name

Content object name

path

Node location path

section_id

Section ID

All sort keys can be used to sort in ascending (“asc”) or descending (“desc”) order. It is also possible to specify multiple sort options in the same fetch function.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'sort_by', hash(
        'class_name', 'asc',
        'published', 'desc'
    )
) )

Returns:

Returns all documents containing the words “ez” and “systems”. The results are sorted by the content class name in ascending order and then by the published time in descending order.

<class_attribute>

Sorting can be done based on a content class attribute field, specified by its ID number or identifier. If the content class attribute datatype extends ezfSolrDocumentFieldBase, the sub-structure can be used as well.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'sort_by', hash(
        'article/title', 'asc'
    )
) )

Returns:

Returns all documents containing the words “ez” and “systems”, sorted by the article title in ascending order.

Example:

fetch( 'ezfind', 'search',
    hash(
        'query', 'eZ Systems',
        'sort_by', hash(
            'article/options/opt1', 'asc'
        )
    )
)

Returns:

Returns all documents containing the words “ez” and “systems”, sorted by the “opt1” part of the article options.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'sort_by', hash( 234, 'asc' )
) )

Returns:

Returns all documents containing the words “ez” and “systems”, sorted by the content class attribute with an ID of “234”, in ascending order.

Facet

The facet parameter is used to define the facet query that should be performed. The results include information about the facets and facet groups relevant to the current search and are returned in addition to the normal query results. It is possible to perform multiple facet queries in one fetch request.

The following facet options are available:

Option

Description

field

The object characteristic that will serve as the facet. This can be a field, specified using the syntax “<class_identifier>/<class_attribute>[/<sub_structure]”.
 The sub-structure is only available for complex datatypes. To enable “<sub_structure>” support, the datatype must contain distinct sub-items (such as the alternative image text for images) and these sub-items must be indexed.
 Other supported characteristics are:

  •  author – content object author
  •  class – content class
  •  translation – translation

query

Facet query. The facet queries are used to specify facets for the sub-selection of content object attributes.
Note : If your query is litteral (i.e. a search term) an can contain Solr special characters (i.e. " or *), then it must be escaped by using solr_escape template operator.

prefix

Limits the facet fields to only list facet groups where the field value starts with the prefix.

sort

Sort by “count” or “alpha”. “alpha” will sort the facet results alpha-numerically by field value.

limit

Maximum number of facet groups to return. The default value is “20”.

offset

Offset. The default value is “0”.

mincount

Returns only facet groups with more results than the specified minimum count. The default value “0”.

missing

If set to “true”, the results will also include facet groups with no results. The default value is “false”.

date.start

Start date for facet. This must be specified using a strict dateTime syntax.

date.end

End date for facet. This must be specified using a strict dateTime syntax.

date.gap

Size of date range.

Below are examples and more detailed descriptions of the different facet options.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'Cabriolet',
    'facet', array(
        hash(
            'field','car/model',
            'limit', 20
        )
    )
) )

Returns:

Returns a list of 10 documents containing the word “cabriolet” and a facet list with 20 groups of car models (this is specific to “model” attributes of objects of the “car” class) also containing the word “cabriolet”.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'Cabriolet',
    'facet', array(
        hash(
            'field', 'car/make',
            'limit', 25 ),
        hash(
            'field', 'car/size',
            'missing', true(),
            'limit', 25
        )
    )
))

Returns:

Returns a list of 10 documents containing the word “cabriolet” and one facet list with 25 groups of car makes (this is specific to “make” attributes of objects of the “car” class) and another facet list with 25 groups of car sizes (this is specific to “size” attributes of objects of the “car” class), both containing the word “cabriolet”. The “car/size” results will also list elements with 0 matching elements.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'facet', array(
        hash( 'query', 'path:2' ),
        hash( query, 'path:5' )
    )
) )

Returns:

Returns a list of 10 documents containing the word “cabriolet” and a facet list with groups in the sub-tree with a parent node with an ID of “2”, and another facet list with groups in the sub-tree with a parent node with an ID of “5”. For more information about facets, see: http://wiki.apache.org/solr/SimpleFacetParameters

Filter

The filter is used when creating faceted search templates for drill-down navigation. Filters are used to limit the search result set without altering the relevancy sort order. Facet results contain filter definitions that can be used directly. Custom filter definitions can also be created. A filter is specified by <class_identifier>/<class_attribute>[/<sub_structure]:<value>. The filter option may be a string or list of strings.

Important note : If the lexical part of your filter is likely to contain Solr special characters (i.e. " or *), then it must be escaped by using solr_escape template operator.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'filter', 'car/in_stock:1'
) )

Returns:

Returns all documents containing the words “ez” and “systems”, having the content object attribute “car/in_stock” with a value of “1”.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'filter', array(
        'car/in_stock:1',
        'car/make:Alfa Romeo',
        'car/model:8C'
    )
) )

Returns:

Returns all documents containing the words “ez” and “systems”, having the content object attribute “car/in_stock” with a value of “1”, the “car/make” attribute with the value “alfa romeo” and the “car/model” attribute with the value “8c”.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'filter', array(
        'car/in_stock:1',
        concat( 'car/make:', '[Alfa Romeo]'|solr_escape )
    )
) )

Returns:

Returns all documents containing the words “ez” and “systems”, having the content object attribute “car/in_stock” with a value of “1” and the “car/make” attribute with the value “[alfa romeo]” (square brackets being special characters in Solr, the value has been escaped).

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'filter', 'car/make:( Audi OR Volvo )'
) )

Returns:

Returns all documents containing the words “ez” and “systems”, having the content object attribute “car/make” with the value “audi” or “volvo”.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'filter', array(
        'path:2',
        'contentclass_id:1'
    )
) )

Returns:

Returns all documents containing the words “ez” and “systems”, in the sub-tree below the node with an ID of “2”, for objects of the content class with an ID of “1”.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'filter', array(
        'or',
         array(
            'and',
            'article/body:hello',
            'article/rating:[1 TO 10]'
        ),
        array(
            'and',
            'article/body:goodbye',
            'article/rating:[10 TO 20]'
        )
    )
) )

Returns:

Returns all articles containing the words “ez” and “systems”, either having both 'hello' present in the body and a rating comprised between 1 and 10, or having both 'goodbye' in the body and a rating comprised between 10 and 20.

Class_id

This parameter is used to limit the search result to specific content classes, using either their identifiers or ID numbers. This can also be achieved by using the filter functionality. class_id may be either a single value or a list of values.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'class_id', 1
) )

Returns:

Returns all documents containing the words “ez” and “systems”, for objects of the content class with an ID of “1”.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'class_id', array( 'folder', 'article' )
) )

Returns:

Returns all documents containing the words “ez” and “systems”, for objects of the Folder and Article content classes.

Subtree_array

This parameter is a list of node IDs that specifies which sub-trees should be included in the search. The same functionality can be achieved with the filter functionality.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'subtree_array', array( 23, 42 )
) )

Returns:

Returns all documents containing the words “ez” and “systems”, from the sub-trees with parent nodes with IDs of “23” and “42”.

Section_id

This parameter is a integer specifying which section should be searched. The same functionality can be achieved with the filter functionality.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'section_id', 3
) )

Returns:

Returns all documents containing the words “ez” and “systems” in the Media section (3).

Ignore_visibility

This parameter is a Boolean which specifies whether or not hidden nodes should be returned in the search results.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'ignore_visibility', true()
) )

Returns:

Returns all documents containing the words “ez” and “systems”, even if they are hidden.

Limitation

This parameter is an associative array overriding the current user's access rights to the read-function of the content-module. The format must exactly match the return format of the eZUser::hasAccessTo() method:

Array elements :
 'accessWord', 'yes' - access allowed
 'no' - access denied
 'limited' - access array describing access included
 'policies', array containing the policy limitations
 'accessList', array describing missing access rights

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'limitation', hash( 'accessWord', 'yes' )
) )

Returns:

Returns all documents containing the words “ez” and “systems”, regardless of the current user's access rights to the read-function of the content-module.

Spell_check

This parameter is an array configuring the spell check behavior of the search. The first parameter is a Boolean value which enables or not the spellchecker. The second one is optional and is only taken into account if the first one is set to true. It contains the identifier of the dictionary to be used. For now only 'default' is supported.
 The spell checking behavior can also be controlled from ezfind.ini.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZy Sistems',
    'spell_check', array(
        true(),
        'default'
    )
) )

Returns:

Result with documents containing the words “ezy” and “sistems” and a spell-check suggestion if Solr considered these two words as incorrectly spelled. The spellcheck feedback is placed under $search_results.SearchExtras.spellcheck and $search_results.SearchExtras.spellcheck_collation, $search_results being the result of the fetch function call.

Query_handler

This parameter is a string defining which Solr search handler should be used. The possible values are listed here:

Handler

Description

standard

the Solr standard handler is called with all syntax supported, searching is done against all searchable fields

simplestandard

the Solr standard handler is called with all syntax supported, searching is done against the aggregated field ezf_df_text

ezpublish

the recommended handler (Solr dismax based) for typical user searches using keywords without boolean or other operators except for + (required) and – (excluding)

heuristic

depending on the presence of special characters indicating boolean, wildcard or fuzzy expressions, either the standard or dismax handler is called.

The default behaviour can be controlled from ezfind.ini, but heuristic is the most common default handler.

Example:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ AND Publish',
    'query_handler', 'standard'
) )

Returns:

Returns all documents containing both words “ez” and “systems”, using the standard handler.

Boost_functions

This parameter is used to pass query-time boosts and is an associative array, with two keys: 'fields' and 'functions'.

  •  'fields' accepts either an associative array or an array, placing a boost factor on given fields. See 'Example 1' and 'Example 1 bis'.
  •  'functions' accepts an array, containing one or more expressions. The latter is not be interpreted and must therefore comply with Solr's Function Query syntax (http://wiki.apache.org/solr/FunctionQuery). See Example 2.

Both can be provided simultaneously.

Example 1:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'boost_functions', hash(
        'fields', array( 'article/title:2' )
    )
) )

Returns:

Returns all documents containing the words “ez” and “systems”. The articles for which the search words were found in the 'title' will be returned first.

Example 1 bis:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'boost_functions', hash(
        'fields', hash( 'article/title', 2 )
    )
)

Returns:

Identical to Example 1.

Example 2:

fetch( 'ezfind', 'search', hash(
    'query', 'eZ Systems',
    'boost_functions', hash(
        'functions', array( 'ord(meta_modified_dt)^2' )
    )
) )

Returns:

Returns all documents containing the words “ez” and “systems”. The most recent documents will be returned first, the result score being influenced by the formula : 'ord(meta_modified_dt)^2'

Ricardo Correia (10/09/2013 9:59 am)

Ricardo Correia (10/09/2013 9:59 am)


Comments

  • publish_date parameter missing in doc

    Apparently publish_date is also supported by ezfind but not mentioned here.
  • moreLikeThis

    fetch(ezfind, MoreLikeThis, hash(<parameters>))

    The second parameter is written with a lower case m -> "moreLikeThis", not with a capitalized M as in the example on top of this page.