Low-level Python client

The OpenSearch low-level Python client (opensearch-py) provides wrapper methods for the OpenSearch REST API so that you can interact with your cluster more naturally in Python. Rather than sending raw HTTP requests to a given URL, you can create an OpenSearch client for your cluster and call the client’s built-in functions. For the client’s complete API documentation and additional examples, see the opensearch-py API documentation.

This getting started guide illustrates how to connect to OpenSearch, index documents, and run queries. For the client source code, see the opensearch-py repo.

Setup

To add the client to your project, install it using pip:

  1. pip install opensearch-py

copy

After installing the client, you can import it like any other module:

  1. from opensearchpy import OpenSearch

copy

Connecting to OpenSearch

To connect to the default OpenSearch host, create a client object with SSL enabled if you are using the Security plugin. You can use the default credentials for testing purposes:

  1. host = 'localhost'
  2. port = 9200
  3. auth = ('admin', 'admin') # For testing only. Don't store credentials in code.
  4. ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA.
  6. # Create the client with SSL/TLS enabled, but hostname verification disabled.
  7. client = OpenSearch(
  8.     hosts = [{'host': host, 'port': port}],
  9.     http_compress = True, # enables gzip compression for request bodies
  10.     http_auth = auth,
  11.     use_ssl = True,
  12.     verify_certs = True,
  13.     ssl_assert_hostname = False,
  14.     ssl_show_warn = False,
  15.     ca_certs = ca_certs_path
  16. )

copy

If you have your own client certificates, specify them in the client_cert_path and client_key_path parameters:

  1. host = 'localhost'
  2. port = 9200
  3. auth = ('admin', 'admin') # For testing only. Don't store credentials in code.
  4. ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA.
  6. # Optional client certificates if you don't want to use HTTP basic authentication.
  7. client_cert_path = '/full/path/to/client.pem'
  8. client_key_path = '/full/path/to/client-key.pem'
  10. # Create the client with SSL/TLS enabled, but hostname verification disabled.
  11. client = OpenSearch(
  12.     hosts = [{'host': host, 'port': port}],
  13.     http_compress = True, # enables gzip compression for request bodies
  14.     http_auth = auth,
  15.     client_cert = client_cert_path,
  16.     client_key = client_key_path,
  17.     use_ssl = True,
  18.     verify_certs = True,
  19.     ssl_assert_hostname = False,
  20.     ssl_show_warn = False,
  21.     ca_certs = ca_certs_path
  22. )

copy

If you are not using the Security plugin, create a client object with SSL disabled:

  1. host = 'localhost'
  2. port = 9200
  4. # Create the client with SSL/TLS and hostname verification disabled.
  5. client = OpenSearch(
  6.     hosts = [{'host': host, 'port': port}],
  7.     http_compress = True, # enables gzip compression for request bodies
  8.     use_ssl = False,
  9.     verify_certs = False,
  10.     ssl_assert_hostname = False,
  11.     ssl_show_warn = False
  12. )

copy

Connecting to Amazon OpenSearch Service

The following example illustrates connecting to Amazon OpenSearch Service:

  1. from opensearchpy import OpenSearch, RequestsHttpConnection, AWSV4SignerAuth
  2. import boto3
  4. host = '' # cluster endpoint, for example: my-test-domain.us-east-1.es.amazonaws.com
  5. region = 'us-west-2'
  6. service = 'es'
  7. credentials = boto3.Session().get_credentials()
  8. auth = AWSV4SignerAuth(credentials, region, service)
  10. client = OpenSearch(
  11.     hosts = [{'host': host, 'port': 443}],
  12.     http_auth = auth,
  13.     use_ssl = True,
  14.     verify_certs = True,
  15.     connection_class = RequestsHttpConnection,
  16.     pool_maxsize = 20
  17. )

copy

Connecting to Amazon OpenSearch Serverless

The following example illustrates connecting to Amazon OpenSearch Serverless Service:

  1. from opensearchpy import OpenSearch, RequestsHttpConnection, AWSV4SignerAuth
  2. import boto3
  4. host = '' # cluster endpoint, for example: my-test-domain.us-east-1.aoss.amazonaws.com
  5. region = 'us-west-2'
  6. service = 'aoss'
  7. credentials = boto3.Session().get_credentials()
  8. auth = AWSV4SignerAuth(credentials, region, service)
  10. client = OpenSearch(
  11.     hosts = [{'host': host, 'port': 443}],
  12.     http_auth = auth,
  13.     use_ssl = True,
  14.     verify_certs = True,
  15.     connection_class = RequestsHttpConnection,
  16.     pool_maxsize = 20
  17. )

copy

Creating an index

To create an OpenSearch index, use the client.indices.create() method. You can use the following code to construct a JSON object with custom settings:

  1. index_name = 'python-test-index'
  2. index_body = {
  3.   'settings': {
  4.     'index': {
  5.       'number_of_shards': 4
  6.     }
  7.   }
  8. }
  10. response = client.indices.create(index_name, body=index_body)

copy

Indexing a document

You can index a document using the client.index() method:

  1. document = {
  2.   'title': 'Moneyball',
  3.   'director': 'Bennett Miller',
  4.   'year': '2011'
  5. }
  7. response = client.index(
  8.     index = 'python-test-index',
  9.     body = document,
  10.     id = '1',
  11.     refresh = True
  12. )

copy

Performing bulk operations

You can perform several operations at the same time by using the bulk() method of the client. The operations may be of the same type or of different types. Note that the operations must be separated by a \n and the entire string must be a single line:

  1. movies = '{ "index" : { "_index" : "my-dsl-index", "_id" : "2" } } \n { "title" : "Interstellar", "director" : "Christopher Nolan", "year" : "2014"} \n { "create" : { "_index" : "my-dsl-index", "_id" : "3" } } \n { "title" : "Star Trek Beyond", "director" : "Justin Lin", "year" : "2015"} \n { "update" : {"_id" : "3", "_index" : "my-dsl-index" } } \n { "doc" : {"year" : "2016"} }'
  3. client.bulk(movies)

copy

Searching for documents

The easiest way to search for documents is to construct a query string. The following code uses a multi-match query to search for “miller” in the title and director fields. It boosts the documents that have “miller” in the title field:

  1. q = 'miller'
  2. query = {
  3.   'size': 5,
  4.   'query': {
  5.     'multi_match': {
  6.       'query': q,
  7.       'fields': ['title^2', 'director']
  8.     }
  9.   }
  10. }
  12. response = client.search(
  13.     body = query,
  14.     index = 'python-test-index'
  15. )

copy

Deleting a document

You can delete a document using the client.delete() method:

  1. response = client.delete(
  2.     index = 'python-test-index',
  3.     id = '1'
  4. )

copy

Deleting an index

You can delete an index using the client.indices.delete() method:

  1. response = client.indices.delete(
  2.     index = 'python-test-index'
  3. )

copy

Sample program

The following sample program creates a client, adds an index with non-default settings, inserts a document, performs bulk operations, searches for the document, deletes the document, and then deletes the index:

  1. from opensearchpy import OpenSearch
  3. host = 'localhost'
  4. port = 9200
  5. auth = ('admin', 'admin') # For testing only. Don't store credentials in code.
  6. ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA.
  8. # Optional client certificates if you don't want to use HTTP basic authentication.
  9. # client_cert_path = '/full/path/to/client.pem'
  10. # client_key_path = '/full/path/to/client-key.pem'
  12. # Create the client with SSL/TLS enabled, but hostname verification disabled.
  13. client = OpenSearch(
  14.     hosts = [{'host': host, 'port': port}],
  15.     http_compress = True, # enables gzip compression for request bodies
  16.     http_auth = auth,
  17.     # client_cert = client_cert_path,
  18.     # client_key = client_key_path,
  19.     use_ssl = True,
  20.     verify_certs = True,
  21.     ssl_assert_hostname = False,
  22.     ssl_show_warn = False,
  23.     ca_certs = ca_certs_path
  24. )
  26. # Create an index with non-default settings.
  27. index_name = 'python-test-index'
  28. index_body = {
  29.   'settings': {
  30.     'index': {
  31.       'number_of_shards': 4
  32.     }
  33.   }
  34. }
  36. response = client.indices.create(index_name, body=index_body)
  37. print('\nCreating index:')
  38. print(response)
  40. # Add a document to the index.
  41. document = {
  42.   'title': 'Moneyball',
  43.   'director': 'Bennett Miller',
  44.   'year': '2011'
  45. }
  46. id = '1'
  48. response = client.index(
  49.     index = index_name,
  50.     body = document,
  51.     id = id,
  52.     refresh = True
  53. )
  55. print('\nAdding document:')
  56. print(response)
  58. # Perform bulk operations
  60. movies = '{ "index" : { "_index" : "my-dsl-index", "_id" : "2" } } \n { "title" : "Interstellar", "director" : "Christopher Nolan", "year" : "2014"} \n { "create" : { "_index" : "my-dsl-index", "_id" : "3" } } \n { "title" : "Star Trek Beyond", "director" : "Justin Lin", "year" : "2015"} \n { "update" : {"_id" : "3", "_index" : "my-dsl-index" } } \n { "doc" : {"year" : "2016"} }'
  62. client.bulk(movies)
  64. # Search for the document.
  65. q = 'miller'
  66. query = {
  67.   'size': 5,
  68.   'query': {
  69.     'multi_match': {
  70.       'query': q,
  71.       'fields': ['title^2', 'director']
  72.     }
  73.   }
  74. }
  76. response = client.search(
  77.     body = query,
  78.     index = index_name
  79. )
  80. print('\nSearch results:')
  81. print(response)
  83. # Delete the document.
  84. response = client.delete(
  85.     index = index_name,
  86.     id = id
  87. )
  89. print('\nDeleting document:')
  90. print(response)
  92. # Delete the index.
  93. response = client.indices.delete(
  94.     index = index_name
  95. )
  97. print('\nDeleting index:')
  98. print(response)

copy