Extended Solr Search API
With your applications deployed, it is expected for data to flow in and out of your Martini instance. But what if you want to query those bits and pieces of information later? This is where Martini's out-of-the-box support for Solr comes handy.
To query indexed data, you can use Apache Solr's API; extended and re-exposed in Martini. You can direct queries meant for Solr to Martini, and use additional, convenient endpoints for performing document searches. You can still query your Solr servers directly (unless they are embedded), but there are plenty of reasons to choose Martini's Solr API over the native Solr API such as:
- Support for document searches in embedded Solr cores via REST
- No need to authenticate your requests to Solr if you're already an authenticated user of Martini
- Additional endpoints that make querying a lot more easier
Which Solr cores can I query using the extended Solr Search API?
You can use this API to query documents in Tracker, the invoke monitor, and any of your connected custom search indices.
Headers
You must include a header in your request to be able to use the API.
To access the 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 an Martini user. |
Path parameters
All endpoints in Martini's Solr API begin with the path:
1 |
|
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>
Perhaps the most important endpoint in the API, this endpoint mirrors the functionality of Solr's native REST API. Thus to fully understand the capabilities and restrictions of this endpoint, one must be familiar with Apache Solr's REST API.
The SearchHandler (select
) is among the most commonly used request
handlers. This handler queries the Solr index. It will be used in the succeeding examples below. To learn more about
other request handlers, please refer to Solr's documentation for request handlers.
Only Solr's SearchHandler is mirrored by Martini
Other handlers such as the UpdateHandler, are not supported. Requests that use unsupported handlers have to be sent directly to the Solr server as Martini cannot act as a proxy.
Request
Path parameters
Parameter name | Data type | Description |
---|---|---|
request-handler | string | The request handler to use during the search. |
Global parameters and headers
For other parameters and headers, see:
Handler configuration
Ensure the handler you want to use is properly configured in solrconfig.xml
for the API to work as expected.
Example
1 2 3 |
|
Response
Content type
application/json
application/xml
text/plain
Example
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 43 44 45 46 47 48 49 50 |
|
List facet count
- Method:
GET
- Path:
/esbapi/v1/solr/<package>/<core>/facets
This endpoint queries the Solr index and generates a facet count using the facet.field
term.
Request
Query parameters
Parameter name | Data type | Required | Description |
---|---|---|---|
facet.field | string | true | The document field that should be treated as facet. You can define multiple facet.field parameters. |
Aside from specifying facet.field
s, other parameters can be used to further
customize the results to your liking — faceting query parameters in particular.
Global parameters and headers
For other parameters and headers, see:
Example
1 2 3 |
|
The cURL request above specified the q
query parameter in order to only do a facet count on documents that have an
endpointType
field with a value of ftp-server
. The facet.field
s requested are endpointName
and packageName
and
so, we should expect the response to show the facet counts of these fields.
Response
Content type
application/json
application/xml
text/plain
Example
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 |
|
Get facet count
- Method:
GET
- Path:
/esbapi/v1/solr/<package>/<core>/facet/<facet-field>
This endpoint is similar to the List facet count endpoint, but facet counting is limited to a single facet field.
Request
Path parameters
Parameter name | Data type | Required | Description |
---|---|---|---|
facet-field | string | true | The document field that should be treated as facet. |
Aside from specifying a facet.field
parameter, other parameters can be used to further
customize the results to your liking — faceting query parameters in particular.
Global parameters and headers
For other parameters and headers, see:
Example
1 2 3 |
|
The cURL request above has the q
query parameter specified in order to do a search for documents whose user
fields
have a value of User_016
. By doing so, the results will be filtered so we only get the facet count of the facet
field packageName
of documents that have a user
field value of User_016
.
Response
Content type
application/json
application/xml
text/plain
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
List facet terms
- Method:
GET
- Path:
/esbapi/v1/solr/<package>/<core>/facet/<facet-field>/names
Lists down all the terms under the specified facet field.
Request
Path parameters
Parameter name | Data type | Required | Description |
---|---|---|---|
facet_field | string | true | The document field that should be treated as facet. |
Aside from specifying a facet.field
parameter, other parameters can be used to further
customize the results to your liking — faceting query parameters in particular.
Global parameters and headers
For other parameters and headers, see:
Example
1 2 3 |
|
The q
query parameter value is *:*
which means the search will match all documents. By doing so, we will be able to
get the terms of the facet field packageName
of all documents.
Response
Content type
application/json
application/xml
text/plain
Example
1 2 3 4 5 |
|
List statistics
- Method:
GET
- Path:
/esbapi/v1/solr/<package>/<core>/stats
Queries the Solr index and generates statistics for numeric, string, and date fields within the document set by
specifying stats.field
.
Request
Query parameters
Parameter name | Data type | Required | Description |
---|---|---|---|
stats.field | string | true | The document field for which statistics should be generated. You can define multiple stats.field parameters to generate multiple statistics. |
stats.calcdistinct | boolean | false | If true , the countDistinct and distinctValues statistics will be computed and included in the response. These calculations can be very expensive for fields that do not have a tiny cardinality, so they are disabled by default. |
Aside from specifying stats.field
, other parameters can be use to customize the
resulting statistics - statistics query parameters in particular.
Global parameters and headers
For other parameters and headers, see:
Example
1 2 3 |
|
The value of stats.field
may seem unusual compared to the previous example but this is just another way to generate
statistics. In this request, we are using the function query instead of just plainly
specifying the document field in stats.field
. The above request will generate statistics that check for frequency
of ftp-server
as a value of endpointType
and Package_01
as a value of packageName
in the Solr index.
Response
Content type
application/json
application/xml
text/plain
Example
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 |
|
Get statistics
- Method:
GET
- Path:
/esbapi/v1/solr/<package>/<core>/stats/<stats-field>
This endpoint is similar to List statistics; the difference is it only gathers the statistics of a single field.
Function queries
Unlike that of List statistics, function queries are not supported here due to character limitations in request paths.
Request
Path parameters
Parameter name | Data type | Required | Description |
---|---|---|---|
stats-field | string | true | The document field for which statistics should be generated. |
Query parameters
Parameter name | Data type | Required | Description |
---|---|---|---|
stats.calcdistinct | boolean | false | If true , the countDistinct and distinctValues statistics will be computed and included the response. These calculations can be very expensive for fields that do not have a tiny cardinality, so they are disabled by default. |
Aside from specifying stats.field
, other parameters can be use to customize the
resulting statistics - statistics query parameters in particular.
Global parameters and headers
For other parameters and headers, see:
Example
1 2 3 |
|
Response
Content type
application/json
application/xml
text/plain
1 2 3 4 5 6 7 8 9 10 11 |
|
Range faceting
- Method:
GET
- Path:
/esbapi/v1/solr/<package>/<core>/rangefacet/<facet-range>
According to the Solr's documentation on range faceting:
You can use range faceting on any date field or any numeric field that supports range queries. This is particularly useful for stitching together a series of range queries (as facet by query) for things like prices.
Working with dates
If you are going to work with date range facets, it's a good idea to read Solr's guide for working with dates.
Request
Path parameters
Parameter name | Data type | Required | Description |
---|---|---|---|
facet_range | string | true | Specifies the field to facet by range. |
Query parameters
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 expressed as a value to be added to the lower bound. For date fields, this should be expressed using DateMathParser 's syntax. |
Aside from the parameters specified above, you can use other Solr parameters to further refine your request - range faceting query parameters in particular.
Global parameters and headers
For other parameters and headers, see:
Example
1 2 3 |
|
The following parameters are present in the request above:
- The
facet-range
path parameter is set totimeReceived
. This is the field we intend to facet by range. - The
facet.range.start
query parameter is set to2020-01-01T00:00:00Z
. This means we'll only do range faceting for values oftimeReceived
that are on or after this date. - The
facet.range.end
query parameter is set to2020-01-02T00:00:00Z
. This means we'll only do range faceting for values oftimeReceived
that are on or before this date. - The
facet.range.gap
query parameter is set to+8HOURS
which will be the interval gap between each range facet. - The
q
query parameter is set to*:*
which means this will match all documents and we'll be applying range faceting for all of them.
Response
Content type
application/json
application/xml
text/plain
Example
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 |
|
Pivot faceting
- Method:
GET
- Path:
/esbapi/v1/solr/<package>/<core>/pivots
Queries the Solr index and generates a table summarizing the results. More accurately, according to the Solr's documentation:
Pivoting is a summarization tool that lets you automatically sort, count, total, or average data stored in a table. The results are typically displayed in a second table showing the summarized data. Pivot faceting lets you create a summary table of the results [from faceting] documents by multiple fields.
Request
Query parameters
Parameter name | Data type | Required | Description |
---|---|---|---|
facet.pivot | boolean | true | Defines the fields to use for the pivot. Defining multiple fields in a single facet.pivot parameter values will create multiple "facet_pivot" sections in the response, this is achieved by separating each field with a comma. You can also define multiple facet.pivot parameters as well to create multiple pivots. |
Aside from the query parameter specified above, you can use other parameters to further refine your request - pivot faceting query parameters, in particular.
Global parameters and headers
For other parameters and headers, see:
Examples
1 2 3 |
|
The following query parameters are present in the request above:
facet.pivot
's value is set topackageName,endpointName
and because of this, the endpoint (as will be seen in the response) will generate a more detailed summary by showing the inner pivot of the parent pivot.q
's value is*
which means it'll match all documents without filtering.
Response
Content type
application/json
application/xml
text/plain
Example
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 |
|
From the response above, we can then conclude that:
- The total number of documents that have a
packageName
field with a value ofPackage_01
is5509
. - The total number of documents that have a
packageName
field with a value ofPackage_01
and anendpointName
field with a value ofEndpoint_02
is2304
. - The total number of documents that have a
packageName
field with a value ofPackage_01
and anendpointName
field with a value ofEndpoint_03
is3205
.