Search API

A query class builds an Elasticsearch request from a SearchQueryParser and runs it against the read indexes. The parameters are described in Query parameters.

from openaleph_search import EntitiesQuery, SearchQueryParser, unpack_result

parser = SearchQueryParser([("q", "jane doe"), ("filter:schema", "Person")])
result = EntitiesQuery(parser).search()
entities = [unpack_result(hit) for hit in result["hits"]["hits"]]

Parameters

`openaleph_search.parse.parser.SearchQueryParser(args, auth=None, limit=None, max_limit=MAX_PAGE)`

Bases: QueryParser

Query parameters of a search, see Query parameters.

Parameters:

Name	Type	Description	Default
`args`	`MultiDict \| dict[str, Any] \| list[tuple[str, Any]]`	URL-style parameters.	required
`auth`	`SearchAuth \| None`	Datasets the search may read, required with the `auth` setting.	`None`
`limit`	`int \| None`	Page size, instead of the `limit` parameter.	`None`
`max_limit`	`int \| None`	Upper bound on the `limit` parameter.	`MAX_PAGE`

Raises:

Type	Description
`RuntimeError`	if `auth` is missing with the `auth` setting.

`openaleph_search.model.SearchAuth`

Bases: BaseModel

Datasets a search may read.

Attributes:

Name	Type	Description
`datasets`	`set[str]`	Readable datasets.
`logged_in`	`bool`	Whether a user is logged in.
`is_admin`	`bool`	Whether the user may read all datasets.
`role`	`str \| None`	Role ID of the user.
`collection_ids`	`set[int]`	Readable OpenAleph collections.

Queries

`openaleph_search.query.base.Query(parser)`

Base class of the search queries: builds an Elasticsearch request body from query parameters and runs it.

Parameters:

Name	Type	Description	Default
`parser`	`SearchQueryParser`	Query parameters.	required

`search()`

Run the query.

Returns:

Type	Description
`ObjectApiResponse`	The Elasticsearch response.

`openaleph_search.query.queries.EntitiesQuery(parser)`

Bases: ExpandNameSynonymsMixin, Query

Search entities by text, filters and facets, as the OpenAleph search does.

`openaleph_search.query.queries.MatchQuery(parser, entity=None, exclude=None, datasets=None, collection_ids=None)`

Bases: EntitiesQuery

Given an entity, find the most similar other entities.

Parameters:

Name	Type	Description	Default
`parser`		Query parameters.	required
`entity`	`EntityProxy \| None`	The entity to match.	`None`
`exclude`		Entity IDs to leave out.	`None`
`datasets`		Only match in these datasets.	`None`
`collection_ids`		Only match in these collections.	`None`

`openaleph_search.query.queries.MoreLikeThisQuery(parser, entity=None, exclude=None, datasets=None, collection_ids=None)`

Bases: EntitiesQuery

Given a document, find documents and pages with similar text.

Parameters:

Name	Type	Description	Default
`parser`		Query parameters.	required
`entity`	`EntityProxy \| None`	The document.	`None`
`exclude`		Entity IDs to leave out.	`None`
`datasets`		Only search these datasets.	`None`
`collection_ids`		Only search these collections.	`None`

`openaleph_search.query.queries.GeoDistanceQuery(parser, entity=None, exclude=None, datasets=None)`

Bases: EntitiesQuery

Given an Address entity, find the nearby addresses.

Parameters:

Name	Description	Default
`parser`	Query parameters.	required
`entity`	The address, with `latitude` and `longitude`.	`None`
`exclude`	Entity IDs to leave out.	`None`
`datasets`	Only search these datasets.	`None`

`openaleph_search.query.queries.PercolatorQuery(parser, text=None, entity_id=None)`

Bases: EntitiesQuery

Find the entities a text or a document mentions, via the percolator queries stored on things-bucket entities (see the percolation setting).

The query parameters of EntitiesQuery apply. Each hit carries the matched spans as _source.surface_forms.

Parameters:

Name	Type	Description	Default
`parser`		Query parameters.	required
`text`	`str \| None`	The text to percolate.	`None`
`entity_id`	`str \| None`	A `Document` or `Pages` entity whose text to percolate, instead of `text`.	`None`

Raises:

Type	Description
`ValueError`	if not exactly one of `text` and `entity_id` is given, or the entity has no text.

`openaleph_search.query.mentions.MentionsQuery(parser, entity_id)`

Bases: _Mentions

Find documents whose text mentions one of the names of an entity, the inverse of PercolatorQuery.

The query parameters of EntitiesQuery apply; search text narrows the mentioning documents further.

Parameters:

Name	Type	Description	Default
`parser`	`SearchQueryParser`	Query parameters.	required
`entity_id`	`str`	The named entity (`Person`, `Company`, ...).	required

Raises:

Type	Description
`ValueError`	if the entity is not indexed or has no names left after `clean_matching_names`.

`openaleph_search.query.mentions.MultiMentionsQuery(parser, source_parser)`

Bases: _Mentions

Find documents whose text mentions any of a filtered set of entities. The source entities are collected on construction; each hit carries the IDs of those it mentions as _source.mention_sources.

Parameters:

Name	Type	Description	Default
`parser`	`SearchQueryParser`	Query parameters of the documents.	required
`source_parser`	`SearchQueryParser`	Query parameters selecting the source entities, with at most 10,000 names (`MAX_SOURCE_NAMES`).	required

Raises:

Type	Description
`ValueError`	if the source entities have more names.

Results

`openaleph_search.index.util.unpack_result(res)`

Turn a document hit from ES into a more traditional JSON object.