This is an old version of the documentation.

Take me to the new one

Or just close this box to continue with this one

  • Downloads
  • Services
  • Resources

    • Documentation
    • Cheatsheets
    • Courses
    • Free Config Review
    • Blog
    • Forum
  • About

    • Manticore Search
    • Clients
  • Contact
3.2.0

Manticore Documentation

  • Introduction
  • Gettting Started
    • Getting started using Docker container
      • Installing and running
      • Running queries
      • Using plain indexes
    • Getting Started using official packages
      • Installing and running
      • Running queries
      • Using plain indexes
    • Migrating from Manticore or Sphinx Search 2.x
      • Index storage engine
      • Kill-list
      • Removed configuration keys
      • Updating var-length attributes
      • Document IDs
    • A guide on configuration file
      • Special suffixes
      • Scripting support
      • Comments
      • Inheritance of index and source declarations
    • A guide on connectivity
      • SphinxAPI protocol
      • SphinxQL protocol
        • MySQL Connectors
        • ODBC
      • HTTP API protocol
    • A guide on indexes
      • Plain indexes
      • Real-Time indexes
      • Local distributed indexes
      • Remote distributed indexes and high availability
      • Replication and cluster
    • A guide on searching
      • Running queries
      • Fulltext Matching
      • Ranking fulltext matches
      • Data tokenization
      • Multi-threaded searching
      • Grouping and faceting
      • Functions
      • Highlighting
      • Tokenizer tester
      • Suggested words
      • Percolate queries
      • Search performance
  • Installation
    • Installing Manticore packages on Debian and Ubuntu
    • Installing Manticore packages on RedHat and CentOS
      • Installing Manticore Search from Manticore yum repository
      • Install Manticore Search using downloaded rpm packages
      • Starting Manticore Search
    • Installing Manticore on Windows
    • Installing Manticore on MacOS
    • Upgrading from Sphinx Search
    • Running Manticore Search in a Docker Container
      • Starting a Manticore Search instance in a container
      • Mounting points
    • Compiling Manticore from source
      • Required tools
      • Required libraries/packages on Linux
      • Optional dependencies
      • General building options
      • Compiling on Linux systems
      • Compiling on Windows
      • Compiling on FreeBSD
      • Recompilation (update)
    • Quick Manticore usage tour
  • Indexing
    • Indexes
      • Plain indexes
      • Real-Time indexes
      • Distributed indexes
      • Templates indexes
      • Percolate indexes
      • Index files
      • Accessing index files
      • Operations on indexes
        • Declaration
        • Loading or discarding indexes
        • Index changes
    • Data Types
      • Document ID
      • Text
      • String
      • Integer
      • Big Integer
      • Timestamps
      • Float
      • JSON
      • Multi-value integer
      • Multi-value big integer
    • Full-text fields
    • Attributes
      • Example sphinx.conf part:
      • Example application code (in PHP):
    • MVA (multi-valued attributes)
    • Restrictions on the source data
    • Charsets, case folding, translation tables, and replacement rules
    • Data sources
    • SQL data sources (MySQL, PostgreSQL)
      • Ranged queries
      • sql_query_post vs. sql_query_post_index
    • xmlpipe2 data source
    • TSV/CSV data source
    • Live index updates
    • Delta index updates
    • Index merging
  • Real-time indexes
    • RT indexes overview
    • Known caveats with RT indexes
    • RT index internals
    • Binary logging
  • Searching
    • Matching modes
    • Boolean query syntax
    • Escaping characters in search queries
    • Extended query syntax
    • Search results ranking
      • Ranking overview
      • Available built-in rankers
        • Legacy matching modes rankers
      • Quick summary of the ranking factors
      • Document-level ranking factors
      • Field-level ranking factors
      • Ranking factor aggregation functions
      • Formula expressions for all the built-in rankers
    • Expressions, functions, and operators
      • Operators
      • Numeric functions
      • Date and time functions
      • Type conversion functions
      • Comparison functions
      • Miscellaneous functions
    • Sorting modes
      • SPH_SORT_TIME_SEGMENTS mode
      • SPH_SORT_EXTENDED mode
      • SPH_SORT_EXPR mode
    • Grouping (clustering) search results
    • Distributed searching
    • Query log formats
      • Plain log format
      • SphinxQL log format
    • MySQL protocol support and SphinxQL
    • Multi-queries
    • Faceted search
      • Aggregations
      • Returned result set
      • Performance
    • Geo Searching
      • Performing distance calculation
      • Searching in polygons
    • Collations
    • Query cache
    • MySQL storage engine (SphinxSE)
      • SphinxSE overview
        • Installing SphinxSE
        • Compiling MySQL 5.0.x with SphinxSE
        • Compiling MySQL 5.1.x with SphinxSE
        • Checking SphinxSE installation
        • Using SphinxSE
      • Building snippets (excerpts) via MySQL
    • MySQL FEDERATED storage engine support
      • MySQL FEDERATED overview
      • Using FEDERATED
    • Percolate query
      • The percolate index
        • ID
        • Query
        • Filters
        • Tags
      • Index schemas
      • Store queries
      • List stored queries
      • Delete queries
      • Search matching queries
      • Meta
      • Reconfigure
      • Distributed indexes made from percolate locals and/or agents (DPQ indexes)
  • Extending
    • UDFs (User Defined Functions)
    • Plugins
    • Ranker plugins
    • Token filter plugins
      • Index-time tokenizer
      • query-time token filter
  • Replication
    • Replication cluster
      • name
      • path
      • nodes
      • options
    • Creating a cluster
    • Joining a cluster
    • Deleting a cluster
    • Managing indexes
    • Managing nodes
    • Write statements
    • Cluster status
    • Cluster parameters
    • Restarting a cluster
    • Cluster with diverged nodes
      • How to recover a cluster
        • Case 1
        • Case 2
        • Case 3
        • Case 4
        • Case 5
        • Case 6
        • Case 7
  • Command line tools reference
    • index_converter command reference
    • indexer command reference
    • indextool command reference
    • searchd command reference
    • spelldump command reference
    • wordbreaker command reference
  • SphinxQL reference
    • ALTER syntax
    • ATTACH INDEX syntax
    • BEGIN, COMMIT, and ROLLBACK syntax
    • BEGIN syntax
    • CALL KEYWORDS syntax
    • CALL PQ syntax
      • Distributed PQ modes
    • CALL QSUGGEST syntax
    • CALL SNIPPETS syntax
    • CALL SUGGEST syntax
    • Comment syntax
    • CREATE FUNCTION syntax
    • CREATE PLUGIN syntax
    • DEBUG syntax
    • DELETE syntax
    • DESCRIBE syntax
      • Percolate index schemas
    • DROP FUNCTION syntax
    • DROP PLUGIN syntax
    • FLUSH ATTRIBUTES syntax
    • FLUSH HOSTNAMES syntax
    • FLUSH LOGS syntax
    • FLUSH RAMCHUNK syntax
    • FLUSH RTINDEX syntax
    • INSERT and REPLACE syntax
      • RT index INSERT features
      • Percolate index INSERT features
    • List of SphinxQL reserved keywords
    • Multi-statement queries
    • OPTIMIZE INDEX syntax
    • RELOAD INDEX syntax
    • RELOAD INDEXES syntax
    • RELOAD PLUGINS syntax
    • REPLACE syntax
    • ROLLBACK syntax
    • SELECT syntax
      • Column list
      • EXIST()
      • SNIPPET()
      • REMOVE_REPEATS()
      • FROM
      • WHERE
      • GROUP BY
      • GROUP_CONCAT()
      • ZONESPANLIST()
      • WITHIN GROUP ORDER BY
      • HAVING
      • ORDER BY
      • LIMIT
      • OPTION
      • FACET
      • Subselects
    • SELECT @@system_variable syntax
    • SET syntax
    • SET TRANSACTION syntax
    • SHOW AGENT STATUS
    • SHOW CHARACTER SET syntax
    • SHOW COLLATION syntax
    • SHOW DATABASES syntax
    • SHOW INDEX SETTINGS syntax
    • SHOW INDEX STATUS syntax
    • SHOW META syntax
    • SHOW PLAN syntax
    • SHOW PLUGINS syntax
    • SHOW PROFILE syntax
    • SHOW STATUS syntax
    • SHOW TABLES syntax
    • SHOW THREADS syntax
    • SHOW VARIABLES syntax
    • SHOW WARNINGS syntax
    • TRUNCATE RTINDEX syntax
    • UPDATE syntax
  • HTTP API reference
    • /sql API
    • /json API
      • json/bulk
      • json/delete
      • json/insert
      • json/pq
        • Store query
        • Search matching document
        • List stored queries
        • Delete stored queries
      • json/replace
      • json/search
        • Fulltext queries
        • Bool queries
        • Filters
        • Sorting
        • Expressions
        • Text highlighting
        • Result set format
        • Query profile
      • json/update
    • SSL
      • Generating SSL files
        • Generate the CA key
        • Generate the CA certificate from the CA key
        • Server Certificate
  • API reference
    • General API functions
      • GetLastError
      • GetLastWarning
      • SetServer
      • SetConnectTimeout
      • SetArrayResult
      • IsConnectError
    • General query settings
      • SetSelect
      • SetLimits
      • SetMaxQueryTime
      • SetOverride
    • Full-text search query settings
      • SetFieldWeights
      • SetIndexWeights
      • SetMatchMode
      • SetRankingMode
      • SetSortMode
      • SetWeights
    • Result set filtering settings
      • SetFilter
      • SetFilterRange
      • SetFilterFloatRange
      • SetFilterString
      • SetIDRange
      • SetGeoAnchor
    • GROUP BY settings
      • SetGroupBy
      • SetGroupDistinct
    • Querying
      • AddQuery
      • Query
      • RunQueries
      • ResetFilters
      • ResetGroupBy
    • Additional functionality
      • BuildExcerpts
      • BuildKeywords
      • EscapeString
      • FlushAttributes
      • Status
      • UpdateAttributes
    • Persistent connections
      • Open
      • Close
  • Configuration reference
    • Common section configuration options
      • lemmatizer_base
      • progressive_merge
      • json_autoconv_keynames
      • json_autoconv_numbers
      • on_json_attr_error
      • plugin_dir
      • icu_data_dir
    • Data source configuration options
      • csvpipe_delimiter
      • mssql_winauth
      • mysql_connect_flags
      • mysql_ssl_cert, mysql_ssl_key, mysql_ssl_ca
      • odbc_dsn
      • sql_attr_bigint
      • sql_attr_bool
      • sql_attr_float
      • sql_attr_json
      • sql_attr_multi
      • sql_attr_string
      • sql_attr_timestamp
      • sql_attr_uint
      • sql_column_buffers
      • sql_db
      • sql_field_string
      • sql_file_field
      • sql_host
      • sql_joined_field
      • sql_pass
      • sql_port
      • sql_query_killlist
      • sql_query_post_index
      • sql_query_post
      • sql_query_pre
      • sql_query_range
      • sql_query
      • sql_ranged_throttle
      • sql_range_step
      • sql_sock
      • sql_user
      • type
      • unpack_mysqlcompress_maxsize
      • unpack_mysqlcompress
      • unpack_zlib
      • xmlpipe_attr_bigint
      • xmlpipe_attr_bool
      • xmlpipe_attr_float
      • xmlpipe_attr_json
      • xmlpipe_attr_multi_64
      • xmlpipe_attr_multi
      • xmlpipe_attr_string
      • xmlpipe_attr_timestamp
      • xmlpipe_attr_uint
      • xmlpipe_command
      • xmlpipe_field
      • xmlpipe_field_string
      • xmlpipe_fixup_utf8
    • Index configuration options
      • access_plain_attrs
      • access_blob_attrs
      • access_doclists
      • access_hitlists
      • agent_blackhole
      • agent_connect_timeout
      • agent_persistent
      • agent_query_timeout
      • agent_retry_count
      • agent
        • Agent mirrors
      • attr_update_reserve
      • bigram_freq_words
      • bigram_index
      • blend_chars
      • blend_mode
      • charset_table
      • dict
      • docstore_block_size
      • docstore_compression
      • docstore_compression_level
      • embedded_limit
      • exceptions
      • expand_keywords
      • global_idf
      • ha_strategy
        • Simple random balancing
        • Adaptive randomized balancing
        • Round-robin balancing
      • hitless_words
      • html_index_attrs
      • html_remove_elements
      • html_strip
      • ignore_chars
      • index_exact_words
      • index_field_lengths
      • index_sp
      • index_token_filter
      • index_zones
      • infix_fields
      • inplace_enable
      • inplace_hit_gap
      • inplace_reloc_factor
      • inplace_write_factor
      • killlist_target
      • local
      • max_substring_len
      • min_infix_len
      • min_prefix_len
      • min_stemming_len
      • min_word_len
      • mirror_retry_count
      • mlock
      • morphology
      • morphology_skip_fields
      • ngram_chars
      • ngram_len
      • ondisk_attrs
      • overshort_step
      • path
      • phrase_boundary
      • phrase_boundary_step
      • prefix_fields
      • preopen
      • read_buffer_docs
      • read_buffer_hits
      • regexp_filter
      • rt_attr_bigint
      • rt_attr_bool
      • rt_attr_float
      • rt_attr_json
      • rt_attr_multi_64
      • rt_attr_multi
      • rt_attr_string
      • rt_attr_timestamp
      • rt_attr_uint
      • rt_field
      • rt_mem_limit
      • source
      • stopwords
      • stopword_step
      • stopwords_unstemmed
      • stored_fields
      • type
      • wordforms
    • indexer program configuration options
      • lemmatizer_cache
      • max_file_field_buffer
      • max_iops
      • max_iosize
      • max_xmlpipe2_field
      • mem_limit
      • on_file_field_error
      • write_buffer
    • searchd program configuration options
      • access_plain_attrs
      • access_blob_attrs
      • access_doclists
      • access_hitlists
      • agent_connect_timeout
      • agent_query_timeout
      • agent_retry_count
      • agent_retry_delay
      • attr_flush_period
      • binlog_flush
      • binlog_max_log_size
      • binlog_path
      • client_timeout
      • collation_libc_locale
      • collation_server
      • data_dir
      • dist_threads
      • docstore_cache_size
      • expansion_limit
      • grouping_in_utc
      • ha_period_karma
      • ha_ping_interval
      • hostname_lookup
      • listen_backlog
      • listen
      • listen_tfo
      • log
      • max_batch_queries
      • max_children
      • max_filters
      • max_filter_values
      • max_open_files
      • max_packet_size
      • mysql_version_string
      • net_workers
      • net_wait_tm
      • net_throttle_accept
      • net_throttle_action
      • node_address
      • ondisk_attrs_default
      • persistent_connections_limit
      • pid_file
      • predicted_time_costs
      • preopen_indexes
      • qcache_max_bytes
      • qcache_thresh_msec
      • qcache_ttl_sec
      • query_log_format
      • query_log_min_msec
      • query_log
      • query_log_mode
      • queue_max_length
      • read_buffer
      • read_buffer_docs
      • read_buffer_hits
      • read_timeout
      • read_unhinted
      • rt_flush_period
      • rt_merge_iops
      • rt_merge_maxiosize
      • seamless_rotate
      • server_id
      • shutdown_timeout
      • shutdown_token
      • snippets_file_prefix
      • sphinxql_state
      • sphinxql_timeout
      • ssl_ca
      • ssl_cert
      • ssl_key
      • subtree_docs_cache
      • subtree_hits_cache
      • thread_stack
      • unlink_old
      • watchdog
      • workers
  • Reporting bugs
    • Bug-tracker
    • Crashes
    • Core dumps
    • Uploading your data
  • Release notes
    • Version 3.2.0, 17 October 2019
      • Features
      • Improvements and changes
      • Bugfixes
    • Version 3.1.2, 22 August 2019
      • Features and Improvements
      • Bugfixes
    • Version 3.1.0, 16 July 2019
      • Features and Improvements
      • Removals
      • Bugfixes
    • Version 3.0.2, 31 May 2019
      • Improvements
      • Removals
      • Deprecations
      • Bugfixes
    • Version 3.0.0, 6 May 2019
      • Features and improvements
      • Behaviour changes
      • Removed directives
    • Version 2.8.2 GA, 2 April 2019
      • Features and improvements
      • Compiling notes
      • Bugfixes
    • Version 2.8.1 GA, 6 March 2019
      • Features and improvements
      • Bugfixes
    • Version 2.8.0 GA, 28 January 2019
      • Improvements
      • Bugfixes
    • Version 2.7.5 GA, 4 December 2018
      • Improvements
      • Bugfixes
    • Version 2.7.4 GA, 1 November 2018
      • Improvements
      • Bugfixes
    • Version 2.7.3 GA, 26 September 2018
      • Improvements
      • Bugfixes
    • Version 2.7.2 GA, 27 August 2018
      • Improvements
      • Bugfixes
    • Version 2.7.1 GA, 4 July 2018
      • Improvements
      • Bugfixes
    • Version 2.7.0 GA, 11 June 2018
      • Improvements
      • Bugfixes
    • Version 2.6.4 GA, 3 May 2018
      • Features and improvements
      • Bugfixes
    • Version 2.6.3 GA, 28 March 2018
      • Improvements
      • Bugfixes
    • Version 2.6.2 GA, 23 February 2018
      • Improvements
      • Bugfixes
    • Version 2.6.1 GA, 26 January 2018
      • Improvements
      • Bugfixes
    • Version 2.6.0, 29 December 2017
      • Features and improvements
      • Bugfixes
      • Upgrade
    • Version 2.5.1, 23 November 2017
      • Features and improvements
      • Bugfixes
    • Version 2.4.1 GA, 16 October 2017
      • Features and improvements
      • Compiling
      • Folders and service
      • Bugfixes
    • Version 2.3.3, 06 July 2017

Looking for the Cheatsheets?

Download

Manticore Search
  • Docs »
  • HTTP API reference »
  • json/search

json/search¶

Searches are accepted at /json/search endpoint. Here’s an example of a simple query:

curl -X POST 'http://manticoresearch:9308/json/search'
    -d '{"index":"test","query":{"match":{"title":"keyword"}}}'

"index" clause sets the list of indexes to search through. You can specify a single index: "index": "test", a comma-separated list of indexes: "index": "test1,test2,test3" or use _all or * to issue the query to all available indexes:

"index": "_all"
"index": "*"

"query" clause contains fulltext queries (if any) and filters. It can be used to organize queries and filters into a tree (using the bool query).

"limit" and "offset" options set the offset into server-side result set and the amount of matches to return to starting from that offset. They work the same as SetLimits in the API and LIMIT and OFFSET in the SphinxQL. Example:

{
  "index":"test",
  "query": { "match_all": {} },
  "limit":100,
  "offset":50,
}

You can also use "size"/"from" synonyms in place of "limit"/"offset".

"max_matches" setting controls how many matches searchd will keep. For more info see SetLimits in the API and MAX_MATCHES in the SphinxQL. Example:

{
  "index":"test",
  "query": { "match_all": {} },
  "max_matches":10000
}

In case the index contains json attributes, they will be injected into output json as inline objects, so you can simple take and work with them (before they were returned as escaped strings, so you had to parse them into json).

Fulltext queries¶

Fulltext queries can be specified either in SphinxQL or in JSON format. One option is to use "query_string" and write queries in SphinxQL:

"query":
{
  "query_string": "Church NOTNEAR/3 street"
}

Another option is to explicitly specify the query tree in JSON. The following fulltext queries are supported:

match

"match" is a simple query that matches the specified keywords in the specified fields

"query":
{
  "match": { "field": "keyword" }
}

Just as in case of indexes, you can specify a list of fields:

"match":
{
  "field1,field2": "keyword"
}

Or you can use "_all" or "*" to search all fields.

You can search all fields except one using "!field":

"match":
{
  "!field1": "keyword"
}

By default keywords are combined using the OR operator. However, you can change that behaviour using the "operator" clause:

"query":
{
  "match":
  {
    "content,title":
    {
      "query":"keyword",
      "operator":"or"
    }
  }
}

"operator" can be set to "or" or "and".

match_phrase

"match_phrase" is a query that matches the entire phrase. It is similar to a phrase operator in SphinxQL. Here’s an example:

"query":
{
  "match_phrase": { "_all" : "had grown quite" }
}

match_all

"match_all" is a query that matches all documents. The syntax looks like this:

"query":
{
  "match_all": {}
}

It can be used to create fullscan queries. However, it is not required as you can just specify the filters without a fulltext query.

Bool queries¶

A bool query matches documents matching boolean combinations of other queries and/or filters. Queries and filters must be specified in "must", "should" or "must_not" sections. Example:

{
  "index":"test",
  "query":
  {
    "bool":
    {
      "must":
      [
        { "match": {"_all":"keyword"} },
        { "range": { "int_col": { "gte": 14 } } }
      ]
    }
  }
}

"must"

Queries and filters specified in the "must" section must match the documents. If several fulltext queries or filters are specified, all of them. This is the equivalent of AND queries in SphinxQL.

"should"

Queries and filters specified in the "should" section should match the documents. If some queries are specified in "must" or "must_not", "should" queries are ignored. On the other hand, if there are no queries other than "should", then at least one of these queries must match a document for it to match the bool query. This is the equivalent of OR queries.

"must_not"

Queries and filters specified in the "must_not" section must not match the documents. If several queries are specified under "must_not", the document matches if none of them match.

Example:

{
  "index": "test1",
  "query":
  {
    "bool":
    {
      "must":
      {
        "match" : { "_all" : "product" }
      },
      "must_not":
      [
        { "match": {"_all":"phone"} },
        { "range": { "price": { "gte": 500 } } }
      ]
    }
  }
}

Queries in SphinxQL format ("query_string") can also be used in bool queries. Example:

{
  "index": "test1",
  "query":
  {
    "bool":
    {
      "must":
      [
        { "query_string" : "product" },
        { "query_string" : "good" }
      ]
    }
  }
}

Filters¶

JSON queries have two distinct entities: fulltext queries and filters. Both can be organised in a tree (using a bool query), but for now filters work only for the root element of the query. For example:

{
  "index":"test",
  "query": { "range": { "price": { "lte": 11 } } }
}

Here’s an example of several filters in a bool query:

{
  "index": "test1",
  "query":
  {
    "bool":
    {
      "must":
      [
        { "match" : { "_all" : "product" } },
        { "range": { "price": { "gte": 500, "lte": 1000 } } },
      ],
      "must_not":
      {
        "range": { "revision": { "lt": 15 } }
      }
    }
  }
}

This is a fulltext query that matches all the documents containing product in any field. These documents must have a price greather or equal than 500 ("gte") and less or equal than 1000 ("lte"). All of these documents must not have a revision less than 15 ("lt").

The following types of filters are supported:

Equality filters

Equality filters are the simplest filters that work with integer, float and string attributes. Example:

{
  "index":"test1",
  "query":
  {
        "equals": { "price": 500 }
  }
}

Range filters

Range filters match documents that have attribute values within a specified range. Example:

{
  "index":"test1",
  "query":
  {
    "range":
    {
      "price":
      {
        "gte": 500,
        "lte": 1000
      }
    }
  }
}

Range filters support the following properties:

  • gte: value must be greater than or equal to
  • gt: value must be greater than
  • lte: value must be less than or equal to
  • lt: value must be less

Geo distance filters

geo_distance filters are used to filter the documents that are within a specific distance from a geo location.

Example:

{
  "index":"test",
  "query":
  {
    "geo_distance":
    {
      "location_anchor": {"lat":49, "lon":15},
      "location_source": {"attr_lat, attr_lon"},
      "distance_type": "adaptive",
      "distance":"100 km"
    }
      }
}
  • location_anchor: specifies the pin location, in degrees. Distances are calculated from this point.
  • location_source: specifies the attributes that contain latitude and longitude.
  • distance_type: specifies distance calculation function. Can be either adaptive or haversine. adaptive is faster and more precise, for more details see GEODIST(). Optional, defaults to adaptive.
  • distance: specifies the maximum distance from the pin locations. All documents within this distance match. The distance can be specified in various units. If no unit is specified, the distance is assumed to be in meters. Here is a list of supported distance units:
    • Meter: m or meters
    • Kilometer: km or kilometers
    • Centimeter: cm or centimeters
    • Millimeter: mm or millimeters
    • Mile: mi or miles
    • Yard: yd or yards
    • Feet: ft or feet
    • Inch: in or inch
    • Nautical mile: NM, nmi or nauticalmiles

location_anchor and location_source properties accept the following latitude/longitude formats:

  • an object with lat and lon keys: { "lat":"attr_lat", "lon":"attr_lon" }
  • a string of the following structure: "attr_lat,attr_lon"
  • an array with the latitude and longitude in the following order: [attr_lon, attr_lat]

Latitude and longitude are specified in degrees.

Sorting¶

Sorting by attributes

Query results can be sorted by one or more attributes. Example:

{
  "index":"test",
  "query":
  {
    "match": { "title": "what was" }
  },
  "sort": [ "_score", "id" ]
}

"sort" specifies an array of attibutes and/or additional properties. Each element of the array can be an attribute name or "_score" if you want to sort by match weights. In that case sort order defaults to ascending for attributes and descending for _score.

You can also specify sort order explicitly. Example:

"sort":
[
  { "price":"asc" },
  "id"
]
  • asc: sort in ascending order
  • desc: sort in descending order

You can also use another syntax and specify sort order via the order property:

"sort":
[
  { "gid": { "order":"desc" } }
]

Sorting by MVA attributes is also supported in JSON queries. Sorting mode can be set via the mode property. The following modes are supported:

  • min: sort by minimum value
  • max: sort by maximum value

Example:

"sort":
[
  { "attr_mva": { "order":"desc", "mode":"max" } }
]

When sorting on an attribute, match weight (score) calculation is disabled by default (no ranker is used). You can enable weight calculation by setting the track_scores property to true:

{
  "index":"test",
  "track_scores":true,
  "query": { "match": { "title": "what was" } },
  "sort": [ { "gid": { "order":"desc" } } ]
}

Sorting by geo distance

Matches can be sorted by their distance from a specified location. Example:

{
  "index": "test",
  "query": { "match_all": {} },
  "sort":
  [
    {
      "_geo_distance":
      {
        "location_anchor": {"lat":41, "lon":32},
        "location_source": [ "attr_lon", "attr_lat" ],
        "distance_type": "adaptive"
      }
    }
  ]
}

location_anchor property specifies the pin location, location_source specifies the attributes that contain latitude and longitude and distance_type selects distance computation function (optional, defaults to “arc”).

Expressions¶

Expressions are supported via script_fields:

{
  "index": "test",
  "query": { "match_all": {} },
  "script_fields":
  {
    "add_all": { "script": { "inline": "( gid * 10 ) | crc32(title)" } },
    "title_len": { "script": { "inline": "crc32(title)" } }
  }
}

In this example two expressions are created: add_all and title_len. First expression calculates ( gid * 10 ) | crc32(title) and stores the result in the add_all attribute. Second expression calculates crc32(title) and stores the result in the title_len attribute.

Only inline expressions are supported for now. The value of inline property (the expression to compute) has the same syntax as SphinxQL expressions.

Text highlighting¶

Fulltext query search results can be highlighted on one or more fields. Field contents has to be stored in string attributes (for now). Here’s an example:

{
  "index": "test",
  "query": { "match": { "content": "and first" } },
  "highlight":
  {
    "fields":
    {
      "content": {},
      "title": {}
    }
  }
}

As a result of this query, the values of string attributes called content and title are highlighted against the query specified in query clause. Highlighted snippets are added in the highlight property of the hits array:

{
  "took":1,
  "timed_out": false,
  "hits":
  {
    "total": 1,
    "hits":
    [
      {
        "_id": "1",
        "_score": 1625,
        "_source":
        {
          "gid": 1,
          "title": "it was itself in this way",
          "content": "first now and then at"
         },
         "highlight":
         {
           "content": [ "<b>first</b> now <b>and</b> then at" ],
           "title": [ "" ]
         }
      }
    ]
  }
}

The following options are supported:

  • fields object contains attribute names with options.

  • encoder can be set to default or html. When set to html, retains html markup when highlighting. Works similar to html_strip_mode=retain in CALL SNIPPETS.

  • highlight_query makes it possible to highlight against a query other than our search query. Syntax is the same as in the main query:

    {
      "index": "test",
      "query": { "match": { "content": "and first" } },
      "highlight":
      {
        "fields": { "content": {}, "title": {} },
        "highlight_query": { "match": { "_all":"on and not" } }
      }
    }
    
  • pre_tags and post_tags set opening and closing tags for highlighted text snippets. They work similar to before_match and after_match options in CALL SNIPPETS. Optional, defaults are <b> and </b>. Example:

    "highlight":
    {
      "fields": { "content": {} },
      "pre_tags": "before_",
      "post_tags": "_after"
    }
    
  • no_match_size works similar to allow_empty in CALL SNIPPETS. If set to zero value, acts as allow_empty=1, e.g. allows empty string to be returned as highlighting result when a snippet could not be generated. Otherwise, the beginning of the field will be returned. Optional, default is 0. Example:

    "highlight":
    {
      "fields": { "content": {} },
      "no_match_size": 0
    }
    
  • order: if set to "score", sorts the extracted passages in order of relevance. Optional. Works similar to weight_order in CALL SNIPPETS. Example:

    "highlight":
    {
      "fields": { "content": {} },
      "order": "score"
    }
    
  • fragment_size sets maximum fragment size in symbols. Can be global or per-field. Per-field options override global options. Optional, default is 256. Works similar to limit in CALL SNIPPETS. Example of per-field usage:

    "highlight":
    {
      "fields": { "content": { "fragment_size": 100 } },
    }
    

    Example of global usage:

    "highlight":
    {
      "fields": { "content": {} },
      "fragment_size": 100
    }
    
  • number_of_fragments: Limits the maximum number of fragments in a snippet. Just as fragment_size, can be global or per-field. Optional, default is 0 (no limit). Works similar to limit_passages in CALL SNIPPETS.

Result set format¶

Query result is sent as a JSON document. Example:

{
  "took":10
  "timed_out": false,
  "hits":
  {
    "total": 2,
    "hits":
    [
      {
        "_id": "1",
        "_score": 1,
        "_source": { "gid": 11 }
      },
      {
        "_id": "2",
        "_score": 1,
        "_source": { "gid": 12 }
      }
    ]
  }
}
  • took: time in milliseconds it took to execute the search
  • timed_out: if the query timed out or not
  • hits: search results. has the following properties:
    • total: total number of matching documents
    • hits: an array containing matches

Query result can also include query profile information, see Query profile.

Each match in the hits array has the following properties:

  • _id: match id
  • _score: match weight, calculated by ranker
  • _source: an array containing the attributes of this match. By default all attributes are included. However, this behaviour can be changed, see below

You can use the _source property to select the fields you want to be included in the result set. Example:

{
  "index":"test",
  "_source":"attr*",
  "query": { "match_all": {} }
}

You can specify the attributes which you want to include in the query result as a string ("_source": "attr*") or as an array of strings ("_source": [ "attr1", "attri*" ]"). Each entry can be an attribute name or a wildcard (*, % and ? symbols are supported).

You can also explicitly specify which attributes you want to include and which to exlude from the result set using the includes and excludes properties:

"_source":
{
  "includes": [ "attr1", "attri*" ],
  "excludes": [ "*desc*" ]
}

An empty list of includes is interpreted as “include all attributes” while an empty list of excludes does not match anything. If an attribute matches both the includes and excludes, then the excludes win.

Query profile¶

You can view the final transformed query tree with all normalized keywords by adding a "profile":true property:

{
  "index":"test",
  "profile":true,
  "query":
  {
    "match_phrase": { "_all" : "had grown quite" }
  }
}

This feature is somewhat similar to SHOW PLAN statement in SphinxQL. The result appears as a profile property in the result set. For example:

"profile":
{
  "query":
  {
    "type": "PHRASE",
    "description": "PHRASE( AND(KEYWORD(had, querypos=1)),  AND(KEYWORD(grown, querypos=2)),  AND(KEYWORD(quite, querypos=3)))",
    "children":
    [
      {
        "type": "AND",
        "description": "AND(KEYWORD(had, querypos=1))",
        "max_field_pos": 0,
        "children":
        [
          {
            "type": "KEYWORD",
            "word": "had",
            "querypos": 1
           }
        ]
      },
      {
        "type": "AND",
        "description": "AND(KEYWORD(grown, querypos=2))",
        "max_field_pos": 0,
        "children":
        [
          {
            "type": "KEYWORD",
            "word": "grown",
            "querypos": 2
          }
        ]
      },
      {
        "type": "AND",
        "description": "AND(KEYWORD(quite, querypos=3))",
        "max_field_pos": 0,
        "children":
        [
          {
            "type": "KEYWORD",
            "word": "quite",
            "querypos": 3
          }
        ]
      }
    ]
  }
}

query property contains the transformed fulltext query tree. Each node contains:

  • type: node type. Can be AND, OR, PHRASE, KEYWORD etc.
  • description: query subtree for this node shown as a string (in SHOW PLAN format)
  • children: child nodes, if any
  • max_field_pos: maximum position within a field
  • word: transformed keyword. Keyword nodes only.
  • querypos: position of this keyword in a query. Keyword nodes only.
  • excluded: keyword excluded from query. Keyword nodes only.
  • expanded: keyword added by prefix expansion. Keyword nodes only.
  • field_start: keyword must occur at the very start of the field. Keyword nodes only.
  • field_end: keyword must occur at the very end of the field. Keyword nodes only.
  • boost: keyword IDF will be multiplied by this. Keyword nodes only.
Next Previous

© Copyright 2017-2020, Manticore Search team.

Built with Sphinx using a theme provided by Read the Docs.
Menu v: 3.2.0
latest
HTML
Single HTML
PDF
3.5.4
HTML
Single HTML
PDF
3.5.2
HTML
Single HTML
PDF
3.5.0
HTML
Single HTML
PDF
3.4.2
HTML
Single HTML
PDF
3.4.0
HTML
Single HTML
PDF
3.3.0
HTML
Single HTML
PDF
3.2.2
HTML
Single HTML
PDF
3.2.0
HTML
Single HTML
PDF
3.1.2
HTML
Single HTML
PDF
3.1.0
HTML
Single HTML
PDF
3.0.2
HTML
Single HTML
PDF
3.0.0
HTML
Single HTML
PDF
2.8.2
HTML
Single HTML
PDF
2.8.1
HTML
Single HTML
PDF
2.8.0
HTML
Single HTML
PDF
2.7.5
HTML
Single HTML
PDF
2.7.4
HTML
Single HTML
PDF
2.7.3
HTML
Single HTML
PDF
2.7.2
HTML
Single HTML
PDF
2.7.1
HTML
Single HTML
PDF
2.7.0
HTML
Single HTML
PDF
2.6.4
HTML
Single HTML
PDF
2.6.3
HTML
Single HTML
PDF
2.6.2
HTML
Single HTML
PDF
2.6.1
HTML
Single HTML
PDF
2.6.0
HTML
Single HTML
PDF
2.5.1
HTML
Single HTML
PDF
2.4.1
HTML
Single HTML
PDF
Links
Project Home
Github