Skip to content

Martini Solr Search API

Martini brings enhanced capabilities to querying data with its out-of-the-box support for [Apache Solr][solr]. This integration not only allows querying [indexed data][custom-search-index-indexing] but also extends and re-exposes the [Apache Solr's API][solr-api-search], offering a more convenient and powerful way to interact with your Solr instances.

Why Use Martini's Extended Solr API?

While direct queries to Solr servers are possible, Martini's extended Solr API offers several compelling advantages:

  • Ease of Use with Embedded Solr Cores: Directly perform document searches in embedded Solr cores using RESTful endpoints.
  • Simplified Authentication: If you're already authenticated as a Martini user, there's no need for separate Solr authentication, streamlining the process.
  • Enhanced Query Endpoints: Benefit from additional endpoints designed to simplify and optimize the querying experience.

Applicable Solr Cores

The extended Solr Search API in Martini is applicable to a range of Solr cores, including:

  • Tracker Core: For querying documents related to Martini's Tracker feature.
  • Invoke Monitor Core: For accessing data in the Invoke Monitor.
  • Custom Search Indices: If you have set up custom search indices, these can also be queried using this extended API.

Note

"Which Solr cores can I query using the extended Solr Search API?" Utilize this API to interact seamlessly with Tracker, the Invoke Monitor, and any connected custom search indices.

Headers

You must include a header in your request to be able to use the API. To access Martini's Solr API, one must either be a Marketplace user or a [Martini user][user-group] under the ESBAdminGroup group.

Header name Data type Description
Authorization string The access token of a Martini user.

Path Parameters

All endpoints in Martini's Solr API begin with the path:

1
/esbapi/v1/solr/<package>/<core>/

The <package> and <core> path parameters must be substituted, as described in the table below:

Parameter name Data type Description
package string The name of the [Martini package][package] where the Solr instance is configured.
core string The name of the target Solr core.

Query Parameters

Martini's Solr Search API simply re-exposes a part of Solr's REST API, hence supported parameters are also shared between the two. In order to fully benefit from what the re-exposed API has to offer, one must have a good understanding of the [Apache Solr REST API][solr-api-search].

Below are resources that can help you get familiar with allowed parameters in both Solr REST APIs:

  • [Common query parameters][solr-api-common-query-parameters] discusses the query parameters common to all Solr parsers.
  • [Faceting query parameters][solr-api-facet-query-parameters] lists the query parameters used for faceting (that is, arranging search results into categories based on indexed terms). You will want to check out [Range faceting][solr-api-range-faceting] and [Pivot faceting][solr-api-pivot-faceting] as they are two of the most common ways to do faceting.
  • [Result grouping][solr-api-result-grouping] describes the parameters you can use for grouping documents together and getting the top documents for each group.
  • [Stats component][solr-api-solr-statistics] explains the parameters you can add to your request in order to get the statistics of the numeric, string, or date fields of your document set.

wt query parameter is unsupported

The [wt query parameter][solr-api-parameter-wt] is unsupported, but the response type can be configured by specifying the Accept header. Commonly used options are:

  • text/plain
  • application/json
  • application/xml

Endpoints

Martini's Solr API exposes a replica of Apache Solr's Search API. In addition to this API however, it also exposes other endpoints for faster searches:

  • [List facet count][search-index-api-list-facet-count]
  • [Get facet count][search-index-api-get-facet-count]
  • [List facet terms][search-index-api-list-facet-terms]
  • [List statistics][search-index-api-list-statistics]
  • [Get statistics][search-index-api-get-statistics]
  • [Range faceting][search-index-api-range-faceting]
  • [Pivot faceting][search-index-api-pivot-faceting]

Solr API

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/<request-handler>

This endpoint is a critical component of Martini's extended Solr API, mirroring the functionality of Solr's native REST API. Understanding [Apache Solr's REST API][solr-api-search] is key to leveraging the full capabilities and navigating the limitations of this endpoint.

One of the most frequently used request handlers is the [SearchHandler][solr-api-search-request-handler] (select), which is employed for querying the Solr index. This handler will be exemplified in the examples below. For information on other request handlers, refer to Solr's [documentation for request handlers][solr-api-request-handler].

Only Solr's SearchHandler is mirrored by Martini

Martini mirrors only the SearchHandler. Other handlers, such as the UpdateHandler, are not supported. Requests employing unsupported handlers must be sent directly to the Solr server, as Martini cannot proxy these requests.

Request

Path Parameters

Parameter name Data type Description
request-handler string The [request handler][solr-api-request-handler] to use during the search.
Global Parameters and Headers

Refer to the following for other parameters and headers:

  • [Headers][search-index-api-headers]
  • [Path Parameters][search-index-api-parameters-path]
  • [Query Parameters][search-index-api-parameters-query]

Handler Configuration

Ensure the handler you intend to use is properly configured in solrconfig.xml for optimal API functionality.

Example Request

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/core/invoke_monitor/select?q=*%3A*&rows=2&cache=false' \
  -H 'Authorization: Bearer <access-token>'

Response

Content Types

  • application/json
  • application/xml
  • text/plain

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
    "responseHeader": {
        "status": 0,
        "QTime": 1,
        "params": {
            "q": "*:*",
            "cache": "false",
            "rows": "2",
            "wt": "json",
            "version": "2.2"
        }
    },
    "response": {
        "numFound": 29,
        "start": 0,
        "docs": [
            {
                "id": "64db237c-7523-4ba1-8bf7-404b30c59a5e",
                "ruleId": -1,
                "timeReceived": "2018-01-24T00:48:15.780Z",
                ...
            },
            {
                "id": "ffad11c0-3669-4afe-844b-68413cd22134",
                ...
            }
        ]
    }
}

List Facet Count

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/facets

This endpoint is designed to query the Solr index and generate a count of facets using the facet.field parameter.

Request

Query Parameters

In addition to the facet.field, which is mandatory, other parameters can be used to tailor the results. Refer to [faceting query parameters][solr-api-facet-query-parameters] for more customization options.

Parameter name Data type Required Description
[facet.field][solr-api-facet-field] string true The document field to be treated as a facet. Multiple facet.field parameters can be defined.
Global Parameters and Headers

For additional parameters and headers, see:

  • [Headers][search-index-api-headers]
  • [Path Parameters][search-index-api-parameters-path]
  • [Query Parameters][search-index-api-parameters-query]

Example Request

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/core/invoke_monitor/facets?q=endpointType%3Aftp-server&facet.field=packageName&facet.field=endpointName' \
  -H 'authorization: Bearer <access-token>'

The above cURL request specifies the q query parameter to perform a facet count on documents with an endpointType field valued ftp-server. The requested facet.fields are endpointName and packageName, hence the response will reflect the facet counts for these fields.

Response

Content Types

  • application/json
  • application/xml
  • text/plain

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
    "facet_field": {
        "packageName": {
            "name": "packageName",
            "facet_count": 3,
            "count": 895,
            "facet": [
                {
                    "name": "Package_00",
                    "count": 335
                },
                {
                    "name": "Package_01",
                    "count": 282
                },
                {
                    "name": "Package_02",
                    "count": 278
                }
            ]
        },
        "endpointName": {
            "name": "endpointName",
            "facet_count": 3,
            "count": 895,
            "facet": [
                {
                    "name": "Endpoint_02",
                    "count": 309
                },
                {
                    "name": "Endpoint_00",
                    "count": 306
                },
                {
                    "name": "Endpoint_01",
                    "count": 280
                }
            ]
        }
    }
}

Get Facet Count

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/facet/<facet-field>

This endpoint functions similarly to the [List facet count][search-index-api-list-facet-count] endpoint, but it specifically limits facet counting to a single facet field.

Request

Path Parameters

The facet.field parameter is a required field that specifies which document field should be treated as a facet.

Parameter name Data type Required Description
[facet-field][solr-api-facet-field] string true The document field to be treated as a facet.

In addition to the facet.field, you can utilize other parameters to refine the results, particularly the [faceting query parameters][solr-api-facet-query-parameters].

Global Parameters and Headers

For additional parameters and headers, refer to:

  • [Headers][search-index-api-headers]
  • [Path Parameters][search-index-api-parameters-path]
  • [Query Parameters][search-index-api-parameters-query]

Example Request

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/core/invoke_monitor/facet/packageName?q=user%3AUser_016' \
  -H 'authorization: Bearer <access-token>'

In the above cURL request, the q query parameter is used to search for documents with the user field value User_016. This filters the results, providing a facet count for the packageName field in documents where user equals User_016.

Response

Content Types

  • application/json
  • application/xml
  • text/plain

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    "name": "packageName",
    "facet_count": 3,
    "count": 895,
    "facet": [
        {
            "name": "Package_00",
            "count": 335
        },
        {
            "name": "Package_01",
            "count": 282
        },
        {
            "name": "Package_02",
            "count": 278
        }
    ]
}

List Facet Terms

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/facet/<facet-field>/names

This endpoint is designed to list all terms under the specified facet field in the Solr index.

Request

Path Parameters

The facet.field parameter is mandatory and specifies the document field that should be treated as a facet.

Parameter name Data type Required Description
[facet_field][solr-api-facet-field] string true The document field to be treated as a facet.

Other parameters, especially [faceting query parameters][solr-api-facet-query-parameters], can be used for further customization of the results.

Global Parameters and Headers

Refer to the following for additional parameters and headers:

  • [Headers][search-index-api-headers]
  • [Path Parameters][search-index-api-parameters-path]
  • [Query Parameters][search-index-api-parameters-query]

Example Request

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/core/invoke_monitor/facet/packageName/names?q=*%3A*' \
  -H 'authorization: Bearer <access-token>'

In this request, the q query parameter is set to *:*, indicating a match for all documents. This allows us to retrieve the terms of the packageName facet field across all documents.

Response

Content Types

  • application/json
  • application/xml
  • text/plain

Example Response

1
2
3
4
5
[
    "Package_01",
    "Package_00",
    "Package_02"
]

List Statistics

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/stats

This endpoint queries the Solr index to generate statistics for numeric, string, and date fields within the document set by specifying stats.field.

Request

Query Parameters

These parameters are critical for defining the fields for which statistics are generated and customizing the statistical analysis.

Parameter name Data type Required Description
stats.field string true The document field for which statistics should be generated. Multiple stats.field parameters can be defined for various statistics.
stats.calcdistinct boolean false If true, calculates countDistinct and distinctValues statistics. Be cautious as these computations can be resource-intensive for fields with large cardinality, thus they are not enabled by default.

In addition to stats.field, other parameters can further tailor the resulting statistics, particularly those found in [statistics query parameters][solr-api-solr-statistics].

Global Parameters and Headers

For additional parameters and headers, refer to:

  • [Headers][search-index-api-headers]
  • [Path Parameters][search-index-api-parameters-path]
  • [Query Parameters][search-index-api-parameters-query]

Example Request

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/core/invoke_monitor/stats?stats.field=%7B!func%7Dtermfreq('\''packageName'\''%2C'\''Package_01'\'')&stats.field=%7B!func%7Dtermfreq('\''endpointType'\''%2C'\''ftp-server'\'')&q=*%3A*' \
  -H 'authorization: Bearer <access-token>'

In this request, stats.field uses a function query approach, rather than just specifying the document field. This generates statistics on the frequency of ftp-server in endpointType and Package_01 in packageName.

Response

Content Types

  • application/json
  • application/xml
  • text/plain

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "stats": {
        "termfreq('endpointType','ftp-server')": {
            "name": "termfreq('endpointType','ftp-server')",
            "min": 0,
            "max": 1,
            "sum": 895,
            "count": 10032,
            "missing": 0,
            "mean": 0.089214513556619,
            "sumOfSquares": 895,
            "stddev": 0.28506733335231
        },
        "termfreq('packageName','Package_01')": {
            "name": "termfreq('packageName','Package_01')",
            "min": 0,
            "max": 1,
            "sum": 3365,
            "count": 10032,
            "missing": 0,
            "mean": 0.33542663476874,
            "sumOfSquares": 3365,
            "stddev": 0.47216292752283
        }
    }
}

Get Statistics

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/stats/<stats-field>

This endpoint is similar to [List statistics][search-index-api-list-statistics] but differs in that it gathers statistics for only a single field. Note that function queries are not supported in this endpoint due to character limitations in request paths.

Function Queries

Function queries, unlike in the [List statistics][search-index-api-list-statistics] endpoint, are not supported here due to character limitations in request paths.

Request

Path Parameters

This parameter specifies the single document field for which statistics will be generated.

Parameter name Data type Required Description
stats-field string true The document field for which statistics should be generated.

Query Parameters

In addition to the stats.field, the following parameter can be used to determine if distinct count calculations should be included.

Parameter name Data type Required Description
stats.calcdistinct boolean false If true, calculates countDistinct and distinctValues. Note: These calculations can be resource-intensive for large cardinality fields and are thus disabled by default.

Other parameters can be used to tailor the resulting statistics, as detailed in [statistics query parameters][solr-api-solr-statistics].

Global Parameters and Headers

For additional parameters and headers, refer to:

  • [Headers][search-index-api-headers]
  • [Path Parameters][search-index-api-parameters-path]
  • [Query Parameters][search-index-api-parameters-query]

Example Request

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/core/invoke_monitor/stats/cost?q=*%3A*' \
  -H 'authorization: Bearer <access-token>'

Response

Content Types

  • application/json
  • application/xml
  • text/plain

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "name": "cost",
    "min": 321,
    "max": 59482,
    "sum": 984732,
    "count": 10032,
    "missing": 0,
    "mean": 3,
    "sumOfSquares": 3245,
    "stddev": 2
}

Range Faceting

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/rangefacet/<facet-range>

Range faceting in Solr is used for date fields or numeric fields that support range queries. It's especially useful for creating a series of range queries for data like prices, as per Solr's [documentation on range faceting][solr-api-range-faceting].

Working with Dates

For date range facets, it's recommended to familiarize yourself with Solr's guide on [working with dates][solr-api-facet-range-gap].

Request

Path Parameters

The facet_range parameter specifies which field to use for range faceting.

Parameter name Data type Required Description
[facet_range][solr-api-facet-range] string true Specifies the field for range faceting.

Query Parameters

These parameters define the range for faceting, including the start, end, and gap of the ranges.

Parameter name Data type Required Description
[facet.range.start][solr-api-facet-range] date true Specifies the lower bound of the ranges.
[facet.range.end][solr-api-facet-range-end] date true Specifies the upper bound of the ranges.
[facet.range.gap][solr-api-facet-range-gap] string true The span of each range. For date fields, use [DateMathParser's syntax][solr-api-date-math-parser].

Additional Solr parameters can be used for more refined requests, such as those in [range faceting query parameters][solr-api-range-faceting].

Global Parameters and Headers

For other parameters and headers, see:

  • [Headers][search-index-api-headers]
  • [Path Parameters][search-index-api-parameters-path]
  • [Query Parameters][search-index-api-parameters-query]

Example Request

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/core/invoke_monitor/rangefacet/timeReceived?facet.range.start=2020-01-01T00%3A00%3A00Z&facet.range.end=2020-01-02T00%3A00%3A00Z&facet.range.gap=%2B8HOUR&q=*%3A*' \
  -H 'authorization: Bearer <access-token>'

This request sets up range faceting on the timeReceived field, with specific start and end times, and an 8-hour interval gap.

Response

Content Types

  • application/json
  • application/xml
  • text/plain

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
    "name": "timeReceived",
    "start": 1577836800000,
    "end": 1577923200000,
    "gap": "+8HOUR",
    "range_value": [
        "2020-01-01T00:00:00Z",
        "2020-01-01T08:00:00Z",
        "2020-01-01T16:00:00Z"
    ],
    "range_count": [
        19,
        19,
        24
    ],
    "counts": [
        {
            "value": "2020-01-01T00:00:00Z",
            "count": 19
        },
        {
            "value": "2020-01-01T08:00:00Z",
            "count": 19
        },
        {
            "value": "2020-01-01T16:00:00Z",
            "count": 24
        }
    ]
}

Pivot Faceting

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/pivots

Pivot faceting in Solr is a powerful tool for summarizing data, creating a summary table of faceted documents by multiple fields. This is well explained in Solr's [pivot faceting documentation][solr-api-pivot-faceting].

Request

Query Parameters

The facet.pivot parameter is crucial for defining the fields to use for the pivot.

Parameter name Data type Required Description
[facet.pivot][solr-api-facet-pivot] boolean true Specifies the fields for the pivot. Multiple fields in a single facet.pivot create multiple "facet_pivot" sections in the response, separated by commas. Multiple facet.pivot parameters can also be defined for additional pivots.

Other parameters can be used to refine your request, such as those found in [pivot faceting query parameters][solr-api-pivot-faceting].

Global Parameters and Headers

For additional parameters and headers, refer to:

  • [Headers][search-index-api-headers]
  • [Path Parameters][search-index-api-parameters-path]
  • [Query Parameters][search-index-api-parameters-query]

Example Request

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/core/invoke_monitor/pivots?facet.pivot=packageName%2CendpointName&q=*' \
  -H 'authorization: Bearer <access-token>'

In this request: - facet.pivot is set to packageName,endpointName, generating a detailed summary with an inner pivot within a parent pivot. - q is set to *, matching all documents without filtering.

Response

Content Types

  • application/json
  • application/xml
  • text/plain

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "facet_pivot": {
        "packageName,endpointName": {
            "field_name": "packageName,endpointName",
            "pivot": [
                {
                    "value": "Package_01",
                    "field": "packageName",
                    "pivot": [
                        {
                            "value": "Endpoint_03",
                            "field": "endpointName",
                            "count": 3205
                        },
                        {
                            "value": "Endpoint_02",
                            "field": "endpointName",
                            "count": 2304
                        }
                    ],
                    "count": 5509
                }
            ]
        }
    }
}

From this response, it can be concluded that: - There are 5509 documents with packageName as Package_01. - Among these, 2304 have endpointName as Endpoint_02 and 3205 have endpointName as Endpoint_03.