Overview

edit

enterprise-search-python is the official Python client for Elastic Enterprise Search, App Search, and Workplace Search.

Compatibility

edit

Current development happens in the main branch.

The library is compatible with all Elastic Enterprise Search versions since 7.x but you have to use a matching major version:

For Elastic Enterprise Search 7.0 and later, use the major version 7 (7.x.y) of the library.

The recommended way to set your requirements in your setup.py or requirements.txt is::

# Elastic Enterprise Search 7.x
elastic-enterprise-search>=7,<8

Example usage

edit
>>> from elastic_enterprise_search import EnterpriseSearch

# Connecting to an instance on Elastic Cloud w/ username and password
>>> ent_search = EnterpriseSearch(
    "https://<...>.ent-search.us-central1.gcp.cloud.es.io",
    http_auth=("elastic", "<password>"),
)
>>> ent_search.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",
    bearer_auth="private-<private key>",
)
>>> app_search.index_documents(
    engine_name="national-parks",
    documents=[{
        "id": "yellowstone",
        "title": "Yellowstone National Park"
    }]
)

All the API calls map the raw REST API as closely as possible, including the distinction between required and optional arguments to the calls. This means that the code makes distinction between positional and keyword arguments; we recommend that people use keyword arguments for all calls for consistency and safety.

Using Python datetimes with timezones

edit

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.

License

edit

enterprise-search-python is available under the Apache-2.0 license.