elastic-enterprise-search 7.10.0b1

Python Elastic Enterprise Search Client

Table of Contents

• Installation
• Getting Started
  • Authentication
  • App Search Signed Search Keys
• API Reference
• License

Installation

The package can be installed from PyPI:

$ python -m pip install --pre elastic-enterprise-search

The version follows the Elastic Stack version so 7.10 is compatible with Enterprise Search released in Elastic Stack 7.10.

NOTE: The package elastic-enterprise-search was previously used as a client for only 'Elastic Workplace Search' before the product was renamed. When installing make sure you receive a version greater than 7.10.0.

Getting Started

Here's how you can get started:

>>> from elastic_enterprise_search import EnterpriseSearch

# Connecting to an instance on Elastic Cloud w/ username and password
>>> ent = EnterpriseSearch(
    "https://<...>.ent-search.us-central1.gcp.cloud.es.io",
    http_auth=("elastic", "<password>"),
)
>>> ent.get_version()
{'number': '7.10.0', 'build_hash': '9d6eb9f067b7d7090c541890c21f6a1e15f29c48', 'build_date': '2020-10-05T16:19:16Z'}

# If you're only planning on using App Search you
# can instantiate App Search namespaced client by itself:
>>> from elastic_enterprise_search import AppSearch

# Connecting to an instance on Elastic Cloud w/ an App Search private key
>>> app_search = AppSearch(
    "https://<...>.ent-search.us-central1.gcp.cloud.es.io",
    http_auth="private-<private key>",
)
>>> app_search.index_documents(
    engine_name="national-parks",
    body=[{
        "id": "yellowstone",
        "title": "Yellowstone National Park"
    }]
)

Authentication

Each service has its own authentication schemes. Using the http_auth property with either a string for a key / token or a tuple of (username, password) for basic authentication will set the proper Authorization HTTP header on the client instance.

• Enterprise Search
  • Basic Authentication (Username / Password)
• App Search
  • Public Search Key
  • Private API Key
  • Private Admin Key
  • Signed Search Key
  • URL Parameters
• Workplace Search
  • Custom Source API Key
  • OAuth for Search

Authenticating with Enterprise Search

from elastic_enterprise_search import EnterpriseSearch

ent = EnterpriseSearch(...)

# Authenticating via Basic Auth for Enterprise Search APIs
ent.http_auth = ("enterprise_search", "<password>")

# Authenticating with Workplace Search
# Custom API Content Source access token
ent.workplace_search.http_auth = "<content source access token>"

# You can also use an authentication method for a single
# request. This is useful for per-user authentication like OAuth:
ent.workplace_search.search(
    body={"query": "That one document"},
    http_auth="oauth-access-token"
)

App Search Signed Search Keys

from elastic_enterprise_search import AppSearch

# Create an AppSearch client authenticated with a search key.
server_side = AppSearch(
    "https://<...>.ent-search.us-central1.gcp.cloud.es.io",
    http_auth="search-..."
)

# Creating a Signed Search Key on the server side...
signed_search_key = server_side.create_signed_search_key(
    api_key=server_side.http_auth,
    api_key_name="<api key name>",
    search_fields={
        "body": {}
    }   
)

# ...then a different client can then
# use the Signed Search key for searches:
client_side = AppSearch(
    "https://<...>.ent-search.us-central1.gcp.cloud.es.io",
    http_auth=signed_search_key
)
resp = client_side.search(
    engine_name="example-engine",
    body={
        ...
    }
)

Working with Datetimes

Python datetime.datetime objects are automatically serialized according to RFC 3339 which requires a timezone to be included. We highly recommend using datetimes that are timezone-aware. When creating a datetime object, use the tzinfo or tz parameter along with python-dateutil to ensure proper timezones on serialized datetime objects.

To get the current day and time in UTC you can do the following:

import datetime
from dateutil import tz

now = datetime.datetime.now(tz=tz.UTC)

⚠️ Datetimes without timezone information will be serialized as if they were within the locally configured timezone. This is in line with HTTP and RFC 3339 specs which state that datetimes without timezone information should be assumed to be local time.

⚠️ Do not use datetime.datetime.utcnow() or utcfromtimestamp()! These APIs don't add timezone information to the resulting datetime which causes the serializer to return incorrect results.

API Reference

A list of APIs for each client along with parameters:

App Search API

Expand for all APIs

AppSearch.get_api_logs()

The API Log displays API request and response data at the Engine level

Parameters:

• engine_name: Name of the engine
• from_date: Filter date from
• to_date: Filter date to
• current_page: The page to fetch. Defaults to 1
• page_size: The number of results per page
• query: Use this to specify a particular endpoint, like analytics, search, curations and so on
• http_status_filter: Filter based on a particular status code: 400, 401, 403, 429, 200
• http_method_filter: Filter based on a particular HTTP method: GET, POST, PUT, PATCH, DELETE
• sort_direction: Would you like to have your results ascending, oldest to newest, or descending, newest to oldest?
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.get_count_analytics()

Returns the number of clicks and total number of queries over a period

Parameters:

• engine_name: Name of the engine
• filters: Analytics filters
• interval: You can define an interval along with your date range. Can be either hour or day
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.create_curation()

Create a new curation

Parameters:

• engine_name: Name of the engine
• queries: List of affected search queries
• promoted_doc_ids: List of promoted document IDs
• hidden_doc_ids: List of hidden document IDs
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.delete_curation()

Delete a curation by ID

Parameters:

• engine_name: Name of the engine
• curation_id: Curation ID
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.get_curation()

Retrieve a curation by ID

Parameters:

• engine_name: Name of the engine
• curation_id: Curation ID
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.put_curation()

Update an existing curation

Parameters:

• engine_name: Name of the engine
• curation_id: Curation ID
• queries: List of affected search queries
• promoted_doc_ids: List of promoted document IDs
• hidden_doc_ids: List of hidden document IDs
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.list_curations()

Retrieve available curations for the engine

Parameters:

• engine_name: Name of the engine
• current_page: The page to fetch. Defaults to 1
• page_size: The number of results per page
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.delete_documents()

Delete documents by ID

Parameters:

• engine_name: Name of the engine
• body: List of document IDs
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.get_documents()

Retrieves one or more documents by ID

Parameters:

• engine_name: Name of the engine
• body: List of document IDs
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.index_documents()

Create or update documents

Parameters:

• engine_name: Name of the engine
• body: List of document to index
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.list_documents()

List all available documents with optional pagination support

Parameters:

• engine_name: Name of the engine
• current_page: The page to fetch. Defaults to 1
• page_size: The number of results per page
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.put_documents()

Partial update of documents

Parameters:

• engine_name: Name of the engine
• body: List of documents to update
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.create_engine()

Creates a new engine

Parameters:

• engine_name: Engine name
• language: Engine language (null for universal)
• type: Engine type
• source_engines: Sources engines list
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.delete_engine()

Delete an engine by name

Parameters:

• engine_name: Name of the engine
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.get_engine()

Retrieves an engine by name

Parameters:

• engine_name: Name of the engine
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.list_engines()

Retrieves all engines with optional pagination support

Parameters:

• current_page: The page to fetch. Defaults to 1
• page_size: The number of results per page
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.log_clickthrough()

Send data about clicked results

Parameters:

• engine_name: Name of the engine
• query_text: Search query text
• document_id: The ID of the document that was clicked on
• request_id: The request ID returned in the meta tag of a search API response
• tags: Array of strings representing additional information you wish to track with the clickthrough
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.add_meta_engine_source()

Add a source engine to an existing meta engine

Parameters:

• engine_name: Name of the engine
• body: List of engine IDs
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.delete_meta_engine_source()

Delete a source engine from a meta engine

Parameters:

• engine_name: Name of the engine
• body: List of engine IDs
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.multi_search()

Run several search in the same request

Parameters:

• engine_name: Name of the engine
• queries: Search queries
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.query_suggestion()

Provide relevant query suggestions for incomplete queries

Parameters:

• engine_name: Name of the engine
• query: A partial query for which to receive suggestions
• fields: List of fields to use to generate suggestions. Defaults to all text fields
• size: Number of query suggestions to return. Must be between 1 and 20. Defaults to 5
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.get_schema()

Retrieve current schema for then engine

Parameters:

• engine_name: Name of the engine
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.put_schema()

Update schema for the current engine

Parameters:

• engine_name: Name of the engine
• body: Schema description
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.search()

Allows you to search over, facet and filter your data

Parameters:

• engine_name: Name of the engine
• body: Search request parameters
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.get_search_settings()

Retrive current search settings for the engine

Parameters:

• engine_name: Name of the engine
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.put_search_settings()

Update search settings for the engine

Parameters:

• engine_name: Name of the engine
• body: Search settings
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.reset_search_settings()

Reset search settings for the engine

Parameters:

• engine_name: Name of the engine
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.create_synonym_set()

Create a new synonym set

Parameters:

• engine_name: Name of the engine
• synonyms: List of synonyms words
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.delete_synonym_set()

Delete a synonym set by ID

Parameters:

• engine_name: Name of the engine
• synonym_set_id: Synonym set ID
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.get_synonym_set()

Retrieve a synonym set by ID

Parameters:

• engine_name: Name of the engine
• synonym_set_id: Synonym set ID
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.put_synonym_set()

Update a synonym set by ID

Parameters:

• engine_name: Name of the engine
• synonym_set_id: Synonym set ID
• synonyms: List of synonyms words
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.list_synonym_sets()

Retrieve available synonym sets for the engine

Parameters:

• engine_name: Name of the engine
• current_page: The page to fetch. Defaults to 1
• page_size: The number of results per page
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.get_top_clicks_analytics()

Returns the number of clicks received by a document in descending order

Parameters:

• engine_name: Name of the engine
• query: Filter clicks over a search query
• current_page: The page to fetch. Defaults to 1
• page_size: The number of results per page
• filters: Analytics filters
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

AppSearch.get_top_queries_analytics()

Returns queries analytics by usage count

Parameters:

• engine_name: Name of the engine
• current_page: The page to fetch. Defaults to 1
• page_size: The number of results per page
• filters: Analytics filters
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

Workplace Search API

Expand for all APIs

WorkplaceSearch.delete_documents()

Deletes a list of documents from a custom content source

Parameters:

• content_source_key: Unique key for a Custom API source, provided upon creation of a Custom API Source
• body: HTTP request body
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

WorkplaceSearch.index_documents()

Indexes one or more new documents into a custom content source, or updates one or more existing documents

Parameters:

• content_source_key: Unique key for a Custom API source, provided upon creation of a Custom API Source
• body: HTTP request body
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

WorkplaceSearch.list_external_identities()

Retrieves all external identities

Parameters:

• content_source_key: Unique key for a Custom API source, provided upon creation of a Custom API Source
• current_page: Which page of results to request
• page_size: The number of results to return in a page
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

WorkplaceSearch.create_external_identity()

Adds a new external identity

Parameters:

• content_source_key: Unique key for a Custom API source, provided upon creation of a Custom API Source
• body: HTTP request body
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

WorkplaceSearch.delete_external_identity()

Deletes an external identity

Parameters:

• content_source_key: Unique key for a Custom API source, provided upon creation of a Custom API Source
• user: The username in context
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

WorkplaceSearch.get_external_identity()

Retrieves an external identity

Parameters:

• content_source_key: Unique key for a Custom API source, provided upon creation of a Custom API Source
• user: The username in context
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

WorkplaceSearch.put_external_identity()

Updates an external identity

Parameters:

• content_source_key: Unique key for a Custom API source, provided upon creation of a Custom API Source
• user: The username in context
• body: HTTP request body
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

WorkplaceSearch.list_permissions()

Lists all permissions for all users

Parameters:

• content_source_key: Unique key for a Custom API source, provided upon creation of a Custom API Source
• current_page: Which page of results to request
• page_size: The number of results to return in a page
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

WorkplaceSearch.remove_user_permissions()

Removes one or more permissions from an existing set of permissions

Parameters:

• content_source_key: Unique key for a Custom API source, provided upon creation of a Custom API Source
• user: The username in context
• body: HTTP request body
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

WorkplaceSearch.search()

search across available sources with various query tuning options

Parameters:

• body: HTTP request body
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

WorkplaceSearch.add_user_permissions()

Adds one or more new permissions atop existing permissions

Parameters:

• content_source_key: Unique key for a Custom API source, provided upon creation of a Custom API Source
• user: The username in context
• body: HTTP request body
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

WorkplaceSearch.get_user_permissions()

Lists all permissions for one user

Parameters:

• content_source_key: Unique key for a Custom API source, provided upon creation of a Custom API Source
• user: The username in context
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

WorkplaceSearch.put_user_permissions()

Creates a new set of permissions or over-writes all existing permissions

Parameters:

• content_source_key: Unique key for a Custom API source, provided upon creation of a Custom API Source
• user: The username in context
• body: HTTP request body
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

Enterprise Search API

Expand for all APIs

EnterpriseSearch.get_health()

Get information on the health of a deployment and basic statistics around resource usage

Parameters:

• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

EnterpriseSearch.get_read_only()

Get the read-only flag's state

Parameters:

• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

EnterpriseSearch.put_read_only()

Update the read-only flag's state

Parameters:

• body: HTTP request body
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

EnterpriseSearch.get_stats()

Get information about the resource usage of the application, the state of different internal queues, etc.

Parameters:

• include: Comma-separated list of stats to return
• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

EnterpriseSearch.get_version()

Get version information for this server

Parameters:

• params: Additional query params to send with the request
• headers: Additional headers to send with the request
• http_auth: Access token or HTTP basic auth username and password to send with the request

License

enterprise-search-python is available under the Apache-2.0 license. For more details see LICENSE.