Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

An API client for Elastic App Search

Project description

Elastic App Search Logo

CircleCI build

A first-party Python client for building excellent, relevant search experiences with Elastic App Search.

Contents


Getting started 🐣

To install the client, use pip:

python -m pip install elastic-app-search

You can also download the project source and run::

python setup.py install

Dependencies

Versioning

This client is versioned and released alongside App Search.

To guarantee compatibility, use the most recent version of this library within the major version of the corresponding App Search implementation.

For example, for App Search 7.3, use 7.3 of this library or above, but not 8.0.

If you are a SaaS user, simply use the most recent version of this library.

Usage

Instantiating a client

>>> from elastic_app_search import Client
>>> host_identifier = 'host-c5s2mj'
>>> api_key = 'private-mu75psc5egt9ppzuycnc2mc3'
>>> client = Client(host_identifier, api_key)

Using with App Search Managed Deploys

The client can be configured to use a managed deploy by adjusting the base_endpoint and use_https parameters. Since managed deploys do not rely on a host_identifier, it can be omitted.

>>> from elastic_app_search import Client
>>> client = Client(
    api_key='private-mu75psc5egt9ppzuycnc2mc3',
    base_endpoint='localhost:3002/api/as/v1',
    use_https=False
)

Indexing: Creating or Updating a Single Document

>>> engine_name = 'favorite-videos'
>>> document = {
      'id': 'INscMGmhmX4',
      'url': 'https://www.youtube.com/watch?v=INscMGmhmX4',
      'title': 'The Original Grumpy Cat',
      'body': 'A wonderful video of a magnificent cat.'
    }
>>> client.index_document(engine_name, document)
{'id': 'INscMGmhmX4'}

Indexing: Creating or Updating Multiple Documents

>>> engine_name = 'favorite-videos'
>>> documents = [
    {
      'id': 'INscMGmhmX4',
      'url': 'https://www.youtube.com/watch?v=INscMGmhmX4',
      'title': 'The Original Grumpy Cat',
      'body': 'A wonderful video of a magnificent cat.'
    },
    {
      'id': 'JNDFojsd02',
      'url': 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
      'title': 'Another Grumpy Cat',
      'body': 'A great video of another cool cat.'
    }
]

>>> client.index_documents(engine_name, documents)
[{'id': 'INscMGmhmX4', 'errors': []}, {'id': 'JNDFojsd02', 'errors': []}]

Indexing: Updating documents (Partial Updates)

>>> engine_name = 'favorite-videos'
>>> documents = [
    {
      'id': 'INscMGmhmX4',
      'title': 'Updated title'
    }
]

>>> client.update_documents(engine_name, documents)

Get Documents

>>> engine_name = 'favorite-videos'
>>> client.get_documents(engine_name, ['INscMGmhmX4'])
[{'id': 'INscMGmhmX4','url': 'https://www.youtube.com/watch?v=INscMGmhmX4','title': 'The Original Grumpy Cat','body': 'A wonderful video of a magnificent cat.'}]

List Documents

>>> engine_name = 'favorite-videos'
>>> client.list_documents(engine_name, current=1, size=20)
{
    'meta': {
        'page': {
        'current': 1,
        'total_pages': 1,
        'total_results': 2,
        'size': 20
        }
    },
    'results': [{'id': 'INscMGmhmX4','url': 'https://www.youtube.com/watch?v=INscMGmhmX4','title': 'The Original Grumpy Cat','body': 'A wonderful video of a magnificent cat.'}]
}

Destroy Documents

>>> engine_name = 'favorite-videos'
>>> client.destroy_documents(engine_name, ['INscMGmhmX4'])
[{'id': 'INscMGmhmX4','result': True}]

Get Schema

>>> engine_name = 'favorite-videos'
>>> client.get_schema(engine_name)
{'name':'text', 'square_km': 'number', 'square_mi': 'text'}

Create/Update Schema

>>> engine_name = 'favorite-videos'
>>> client.update_schema(engine_name, {'square_km': 'text'})
{'square_km': 'text'}
>>> client.update_schema(engine_name, {'square_mi': 'text'})
{'square_km': 'text', 'square_mi': 'text'}
>>> client.update_schema(engine_name, {'square_km': 'number'})
{'square_km': 'number', 'square_mi': 'text'}

List Engines

>>> client.list_engines(current=1, size=20)
{
    'meta': {
        'page': {
        'current': 1,
        'total_pages': 1,
        'total_results': 2,
        'size': 20
        }
    },
    'results': [{'name': 'favorite-videos'}, {'name': 'another-engine'}]
}

Get an Engine

>>> client.get_engine('favorite-videos')
{'name': 'favorite-videos'}

Create an Engine

>>> client.create_engine('favorite-videos', 'en')
{'name': 'favorite-videos', 'type': 'default', 'language': 'en'}

Destroy an Engine

>>> client.destroy_engine('favorite-videos')
{'deleted': True}

List all synonym sets in an engine

With default pagination (a page size of 20)

>>> client.list_synonym_sets('us-national-parks')
{
  'meta': {
    'page': {
      'current': 1,
      'total_pages': 1,
      'total_results': 3,
      'size': 20
    }
  },
  'results': [
    {
      'id': 'syn-5b11ac66c9f9292013220ad3',
      'synonyms': [
        'park',
        'trail'
      ]
    },
    {
      'id': 'syn-5b11ac72c9f9296b35220ac9',
      'synonyms': [
        'protected',
        'heritage'
      ]
    },
    {
      'id': 'syn-5b11ac66c9f9292013220ad3',
      'synonyms': [
        'hectares',
        'acres'
      ]
    }
  ]
}

With custom pagination

>>> client.list_synonym_sets('us-national-parks', size=1, current=1)
{
  'meta': {
    'page': {
      'current': 1,
      'total_pages': 3,
      'total_results': 3,
      'size': 1
    }
  },
  'results': [
    {
      'id': 'syn-5b11ac66c9f9292013220ad3',
      'synonyms': [
        'park',
        'trail'
      ]
    }
  ]
}

Get a single synonym set

>>> client.get_synonym_set('us-national-parks', 'syn-5b11ac66c9f9292013220ad3')
{
  'id': 'syn-5b11ac66c9f9292013220ad3',
  'synonyms': [
    'park',
    'trail'
  ]
}

Create a synonym set

>>> client.create_synonym_set('us-national-parks', ['park', 'trail'])
{
  'id': 'syn-5b11ac72c9f9296b35220ac9',
  'synonyms': [
    'park',
    'trail'
  ]
}

Update a synonym set

>>> client.update_synonym_set('us-national-parks', 'syn-5b11ac72c9f9296b35220ac9', ['park', 'trail', 'ground'])
{
  'id': 'syn-5b11ac72c9f9296b35220ac9',
  'synonyms': [
    'park',
    'trail',
    'ground'
  ]
}

Destroy a synonym set

>>> client.destroy_synonym_set('us-national-parks', 'syn-5b11ac66c9f9292013220ad3')
{
  'deleted': True
}

Searching

>>> client.search('favorite-videos', 'grumpy cat', {})
{'meta': {'page': {'current': 1, 'total_pages': 1, 'total_results': 2, 'size': 10}, ...}, 'results': [...]}

Multi-Search

>>> client.multi_search('favorite-videos', [{
  'query': 'cat',
  'options': { 'search_fields': { 'title': {} }}
},{
  'query': 'dog',
  'options': { 'search_fields': { 'body': {} }}
}])
[{'meta': {...}, 'results': [...]}, {'meta': {...}, 'results': [...]}]

Query Suggestion

>>> client.query_suggestion('favorite-videos', 'cat', {
  'size': 10,
  'types': {
    'documents': {
      'fields': ['title']
    }
  }
})
{'results': {'documents': [{'suggestion': 'cat'}]}, 'meta': {'request_id': '390be384ad5888353e1b32adcfaaf1c9'}}

Clickthrough Tracking

>>> client.click(engine_name, {'query': 'cat', 'document_id': 'INscMGmhmX4'})

Create a Signed Search Key

Creating a search key that will only search over the body field.

>>> api_key = 'private-mu75psc5egt9ppzuycnc2mc3'
>>> api_key_name = 'my-api-token'
>>> signed_search_key = Client.create_signed_search_key(api_key, api_key_name, {'search_fields': { 'body': {}}})
>>> client = Client(host_identifier, signed_search_key)

Running tests

python setup.py test

FAQ 🔮

Where do I report issues with the client?

If something is not working as expected, please open an issue.

Where can I learn more about App Search?

Your best bet is to read the documentation.

Where else can I go to get help?

You can checkout the Elastic App Search community discuss forums.

Contribute 🚀

We welcome contributors to the project. Before you begin, a couple notes:

License 📗

Apache 2.0 © Elastic

Thank you to all the contributors!

Project details


Download files

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

Files for elastic-app-search, version 7.4.0
Filename, size File type Python version Upload date Hashes
Filename, size elastic-app-search-7.4.0.tar.gz (11.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page