Skip to content
This repository has been archived by the owner on Sep 1, 2021. It is now read-only.

elastic/app-search-python

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

95 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

โš ๏ธ This client is deprecated โš ๏ธ

As of Enterprise Search version 7.10.0, we are directing users to the new Enterprise Search Python Client and deprecating this client.

This client will be compatible with all Enterprise Search 7.x releases, but will not be compatible with 8.x releases. Our development effort on this project will be limited to bug fixes. All future enhancements will be focused on the Enterprise Search Python Client.

Thank you! - Elastic

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 using the SaaS version available on swiftype.com of App Search, you should use the version 7.5.x of the client.

Usage

Instantiating a client

Using this client assumes that you have already an instance of Elastic App Search up and running.

The client can be instantiated using the base_endpoint, api_key and use_https parameters:

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

Notes:

The [api_key] authenticates requests to the API. You can use any key type with the client, however each has a different scope. For more information on keys, check out the documentation.

The base_endpoint must exclude the protocol and include the api/as/v1 prefix. This can typically be found in the Credentials tab within the App Search Dashboard.

Set use_https to True or False depending how your server is configured. Often times it will be False when running in development on localhost and True for production environments.

The following is example of a configuration for Elastic Cloud:

>>> from elastic_app_search import Client
>>> client = Client(
    base_endpoint='77bf13bc2e9948729af339a446b06ddcc.app-search.us-east-1.aws.found.io/api/as/v1',
    api_key='private-mu75psc5egt9ppzuycnc2mc3',
    use_https=True
)

Swiftype.com App Search users:

When using the SaaS version available on swiftype.com of App Search, you can configure the client using your host_identifier instead of the base_endpoint parameter. The host_identifier can be found within the Credentials menu.

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

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 = 'search-xxxxxxxxxxxxxxxxxxxxxxxx'
>>> api_key_name = 'search-key' # This name must match the name of the key above from your App Search dashboard
>>> signed_search_key = Client.create_signed_search_key(api_key, api_key_name, {'search_fields': { 'body': {}}})
>>> client = Client(
    base_endpoint='localhost:3002/api/as/v1',
    api_key=signed_search_key,
    use_https=False
)

Create a Meta Engine

>>> client.create_meta_engine(
    engine_name=engine_name,
    source_engines=[
        'source-engine-1',
        'source-engine-2'
    ]
)
{'source_engines': ['source-engine-1', 'source-engine-2'], 'type': 'meta', 'name': 'my-meta-engine'}

Add a Source Engine to a Meta Engine

>>> client.add_meta_engine_sources('my-meta-engine', ['source-engine-3'])
{'source_engines': ['source-engine-1', 'source-engine-2', 'source-engine-3'], 'type': 'meta', 'name': 'my-meta-engine'}

Remove a Source Engine from a Meta Engine

>>> client.delete_meta_engine_sources('my-meta-engine', ['source-engine-3'])
{'source_engines': ['source-engine-1', 'source-engine-2'], 'type': 'meta', 'name': 'my-meta-engine'}

Search the API logs

>>> client.get_api_logs('my-meta-engine', {
  "filters": {
    "date": {
      "from": "2020-03-30T00:00:00+00:00",
      "to": "2020-03-31T00:00:00+00:00"
    },
    "status": "429"
  }
})
{
    'results': [],
    'meta': {
        'query': '',
        'filters': {
            'date': {
                'from': '2020-03-27T00:00:00+00:00',
                'to': '2020-03-31T00:00:00+00:00'
            },
            'status': '429'
        },
        'sort_direction': 'asc',
        'page': {
            'current': 1,
            'total_pages': 0,
            'total_results': 0,
            'size': 10
        }
    }
}

Get search settings

>>> client.get_search_settings(engine_name='us-national-parks')
{
  "search_fields": {
    "name": {
      "weight": 1
    },
    "description": {
      "weight": 1
    }
  },
  "result_fields": {
    "name": {
      "raw": {}
    },
    "description": {
      "raw": {}
    }
  },
  "boosts": {}
}

Update search settings

>>> client.update_search_settings(
  engine_name='us-national-parks',
  search_settings={
    "search_fields": {
      "name": {
        "weight": 2
      },
      "description": {
        "weight": 1
      }
    },
    "result_fields": {
      "name": {
        "raw": {}
      },
      "description": {
        "raw": {}
      }
    },
    "boosts": {}
  }
)
{
  "search_fields": {
    "name": {
      "weight": 2
    },
    "description": {
      "weight": 1
    }
  },
  "result_fields": {
    "name": {
      "raw": {}
    },
    "description": {
      "raw": {}
    }
  },
  "boosts": {}
}

Reset search settings

>>> client.reset_search_settings(engine_name='us-national-parks')
{
  "search_fields": {
    "name": {
      "weight": 1
    },
    "description": {
      "weight": 1
    }
  },
  "boosts": {}
}

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!