elastic-enterprise-search

Python Elastic Enterprise Search Client

These details have been verified by PyPI

Maintainers

ezimuel jasonstoltz joshmock qhoxie quentinp yakhinvadim

These details have not been verified by PyPI

Project links

Project description

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

Project details

These details have been verified by PyPI

Maintainers

ezimuel jasonstoltz joshmock qhoxie quentinp yakhinvadim

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

8.11.0

Nov 13, 2023

8.10.0

Oct 11, 2023

8.4.0

Aug 25, 2022

8.3.0

Jul 6, 2022

8.2.0

May 5, 2022

8.1.0a1 pre-release

Mar 23, 2022

7.17.0

Mar 7, 2022

7.16.0

Dec 29, 2021

7.15.0

Sep 29, 2021

7.14.0

Aug 5, 2021

7.13.0

May 25, 2021

7.12.0

Mar 23, 2021

7.11.0

Feb 10, 2021

This version

7.10.0b1 pre-release

Nov 11, 2020

7.10.0a1 pre-release

Nov 5, 2020

0.2.1 yanked

Feb 14, 2020

Reason this release was yanked:

Users should migrate to v7.10.0+

0.2.0 yanked

Oct 17, 2019

Reason this release was yanked:

Users should migrate to v7.10.0+

0.1.0 yanked

Aug 19, 2019

Reason this release was yanked:

Users should migrate to v7.10.0+

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

elastic-enterprise-search-7.10.0b1.tar.gz (31.8 kB view details)

Uploaded Nov 11, 2020 Source

Built Distribution

elastic_enterprise_search-7.10.0b1-py2.py3-none-any.whl (26.9 kB view details)

Uploaded Nov 11, 2020 Python 2 Python 3

File details

Details for the file elastic-enterprise-search-7.10.0b1.tar.gz.

File metadata

Download URL: elastic-enterprise-search-7.10.0b1.tar.gz
Upload date: Nov 11, 2020
Size: 31.8 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.6.0 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.5

File hashes

Hashes for elastic-enterprise-search-7.10.0b1.tar.gz
Algorithm	Hash digest
SHA256	`abe00fa90808ac46e2a4d07208b4945e1a08a6c921317dba9b1f46bf1e845648`
MD5	`f523b6e427bad84740894312c7783fc4`
BLAKE2b-256	`3b0b8e2093cfbec82906c2e906abaf2b4bcd624e445e46e5a115359ba1df523d`

See more details on using hashes here.

File details

Details for the file elastic_enterprise_search-7.10.0b1-py2.py3-none-any.whl.

File metadata

Download URL: elastic_enterprise_search-7.10.0b1-py2.py3-none-any.whl
Upload date: Nov 11, 2020
Size: 26.9 kB
Tags: Python 2, Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.6.0 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.5

File hashes

Hashes for elastic_enterprise_search-7.10.0b1-py2.py3-none-any.whl
Algorithm	Hash digest
SHA256	`bdf3fc7cf2ddbc1e57cbc5f828dd553848c4adca87ac96bc5bbcc7c430530e11`
MD5	`1c6546817dff897891bb25878a9cd4ad`
BLAKE2b-256	`497ee9593c45cc0f3bf2fe0269b1ba1466984a8c77a77d8189fff28082efac55`