Martini Solr Search API

Martini brings enhanced capabilities to querying data with its out-of-the-box support for Apache Solr. This integration not only allows querying indexed data but also extends and re-exposes the Apache Solr's API, 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 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 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.

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

Common query parameters discusses the query parameters common to all Solr parsers.
Faceting 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 and Pivot faceting as they are two of the most common ways to do faceting.
Result grouping describes the parameters you can use for grouping documents together and getting the top documents for each group.
Stats component 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 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
Get facet count
List facet terms
List statistics
Get statistics
Range faceting
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 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 (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.

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 to use during the search.

Handler Configuration

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

Example Request

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

{
    "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",
                ...
            }
        ]
    }
}

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 for more customization options.

Parameter name	Data type	Required	Description
facet.field	string	true	The document field to be treated as a facet. Multiple `facet.field` parameters can be defined.

Example Request

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

{
    "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
                }
            ]
        }
    }
}

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

This endpoint functions similarly to the 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	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.

Example Request

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

{
    "name": "packageName",
    "facet_count": 3,
    "count": 895,
    "facet": [
        {
            "name": "Package_00",
            "count": 335
        },
        {
            "name": "Package_01",
            "count": 282
        },
        {
            "name": "Package_02",
            "count": 278
        }
    ]
}

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	string	true	The document field to be treated as a facet.

Other parameters, especially faceting query parameters, can be used for further customization of the results.

Example Request

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

[
    "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.

Example Request

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

{
    "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 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 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.

Example Request

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

{
    "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.

Working with Dates

For date range facets, it's recommended to familiarize yourself with Solr's guide on working with dates.

Request

Path Parameters

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

Parameter name	Data type	Required	Description
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	date	true	Specifies the lower bound of the ranges.
facet.range.end	date	true	Specifies the upper bound of the ranges.
facet.range.gap	string	true	The span of each range. For date fields, use `DateMathParser`'s syntax.

Additional Solr parameters can be used for more refined requests, such as those in range faceting query parameters.

Example Request

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

{
    "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.

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	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.

Example Request

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

{
    "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.

Martini Solr Search API

Why Use Martini's Extended Solr API?

Applicable Solr Cores

Headers

Path Parameters

Query Parameters

Endpoints

Solr API

Request

Response

List Facet Count

Request

Response

Get Facet Count

Request

Response

List Facet Terms

Request

Response

List Statistics

Request

Response

Get Statistics

Request

Response

Range Faceting

Request

Response

Pivot Faceting

Request

Response