From 0bf8624824ed4954e2ad3eda2464552c5aab3c5e Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 19 Aug 2021 12:56:53 -0700 Subject: [PATCH 1/9] Getting started content for Python --- _clients/java-rest-high-level.md | 2 +- _clients/python.md | 122 +++++++++++++++++++++++++++++++ 2 files changed, 123 insertions(+), 1 deletion(-) create mode 100644 _clients/python.md diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index 1dcf1563..3f7260cf 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -1,7 +1,7 @@ --- layout: default title: Java high-level REST client -nav_order: 97 +nav_order: 60 --- # Java high-level REST client diff --git a/_clients/python.md b/_clients/python.md new file mode 100644 index 00000000..1a5bf9b0 --- /dev/null +++ b/_clients/python.md @@ -0,0 +1,122 @@ +--- +layout: default +title: Python client +nav_order: 70 +--- + +# Python client + +The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. + + +## Setup + +To add the client to your project, install it using pip: + +```bash +pip install +``` + +Then import it like any other module: + +```python +from opensearch import OpenSearch +``` + + +## Sample code + +```python +from opensearch import OpenSearch + +host = 'localhost' +port = 9200 +auth = ('admin', 'admin') # For testing only. Don't store credentials in code. +ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA + +# Optional client certificates if you don't want to use HTTP basic authentication. +# client_cert_path = '/full/path/to/client.pem' +# client_key_path = '/full/path/to/client-key.pem' + +# Create the client with SSL/TLS enabled, but hostname verification disabled. +client = OpenSearch( + hosts = [{'host': host, 'port': port}], + http_compress=True, # enables gzip compression for request bodies + http_auth = auth, + # client_cert = client_cert_path, + # client_key = client_key_path, + use_ssl = True, + verify_certs = True, + ssl_assert_hostname = False, + ssl_show_warn = False, + ca_certs = ca_certs_path +) + +# Create an index with non-default settings. +index_name = 'python-test-index3' +index_body = { + 'settings': { + 'index': { + 'number_of_shards': 4 + } + } +} + +response = client.indices.create(index_name, body=index_body) +print('\nCreating index:') +print(response) + +# Add a document to the index. +document = { + 'title': 'Moneyball', + 'director': 'Bennett Miller', + 'year': '2011' +} +id = '1' + +response = client.index( + index=index_name, + body=document, + id=id, + refresh=True +) + +print('\nAdding document:') +print(response) + +# Search for the document. +q = 'miller' +query = { + 'size': 5, + 'query': { + 'multi_match': { + 'query': q, + 'fields': ['title^2', 'director'] + } + } +} + +response = client.search( + body=query, + index=index_name +) +print('\nSearch results:') +print(response) + +# Delete the document. +response = client.delete( + index=index_name, + id=id +) + +print('\nDeleting document:') +print(response) + +# Delete the index. +response = client.indices.delete( + index=index_name +) + +print('\nDeleting index:') +print(response) +``` From 9ce5d95786a3baf50be225cdf6c44a3943ff2988 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 19 Aug 2021 13:23:14 -0700 Subject: [PATCH 2/9] Clean up spacing --- _clients/python.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/_clients/python.md b/_clients/python.md index 1a5bf9b0..0a44cfa9 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -32,7 +32,7 @@ from opensearch import OpenSearch host = 'localhost' port = 9200 auth = ('admin', 'admin') # For testing only. Don't store credentials in code. -ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA +ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA. # Optional client certificates if you don't want to use HTTP basic authentication. # client_cert_path = '/full/path/to/client.pem' @@ -41,7 +41,7 @@ ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use int # Create the client with SSL/TLS enabled, but hostname verification disabled. client = OpenSearch( hosts = [{'host': host, 'port': port}], - http_compress=True, # enables gzip compression for request bodies + http_compress = True, # enables gzip compression for request bodies http_auth = auth, # client_cert = client_cert_path, # client_key = client_key_path, @@ -75,10 +75,10 @@ document = { id = '1' response = client.index( - index=index_name, - body=document, - id=id, - refresh=True + index = index_name, + body = document, + id = id, + refresh = True ) print('\nAdding document:') @@ -97,16 +97,16 @@ query = { } response = client.search( - body=query, - index=index_name + body = query, + index = index_name ) print('\nSearch results:') print(response) # Delete the document. response = client.delete( - index=index_name, - id=id + index = index_name, + id = id ) print('\nDeleting document:') @@ -114,7 +114,7 @@ print(response) # Delete the index. response = client.indices.delete( - index=index_name + index = index_name ) print('\nDeleting index:') From 30facfe628124b75cf17d44c90e946a20b1ce8ca Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 19 Aug 2021 14:38:30 -0700 Subject: [PATCH 3/9] Typo --- _clients/python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/python.md b/_clients/python.md index 0a44cfa9..879513ce 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -6,7 +6,7 @@ nav_order: 70 # Python client -The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. +The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests with raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. ## Setup From ac9acb3c62287e1403fc0ad7c29cf28c1ddaee8e Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 26 Aug 2021 09:15:50 -0700 Subject: [PATCH 4/9] Adds some statements around compatibility Should (hopefully) apply to all clients. --- _clients/index.md | 14 +++++++++++++- _clients/python.md | 2 ++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/_clients/index.md b/_clients/index.md index bdf2bf05..3880a3bb 100644 --- a/_clients/index.md +++ b/_clients/index.md @@ -9,6 +9,18 @@ redirect_from: # OpenSearch client compatibility +OpenSearch provides clients for several popular programming languages, with more coming. In general, clients are compatible with clusters running the same major version of OpenSearch (`major.minor.patch`). + +For example, a 1.0.0 client works with an OpenSearch 1.1.0 cluster, but might not support any non-breaking API changes in OpenSearch 1.1.0. A 1.2.0 client works with the same cluster, but might allow you to pass unsupported options in certain functions. We recommend using the same version for both, but if your tests pass after a cluster upgrade, you don't necessarily need to upgrade your clients immediately. + +* [OpenSearch Java client]({{site.url}}{{site.baseurl}}/clients/java/) +* [OpenSearch Python client]({{site.url}}{{site.baseurl}}/clients/python/) +* [OpenSearch JavaScript (Node.js) client]({{site.url}}{{site.baseurl}}/clients/nodejs/) +* [OpenSearch Go client]({{site.url}}{{site.baseurl}}/clients/golang/) + + +## Legacy clients + Most clients that work with Elasticsearch OSS 7.10.2 *should* work with OpenSearch, but the latest versions of those clients might include license or version checks that artificially break compatibility. This page includes recommendations around which versions of those clients to use for best compatibility with OpenSearch. Client | Recommended version @@ -18,7 +30,7 @@ Client | Recommended version [Python Elasticsearch client](https://pypi.org/project/elasticsearch/7.13.4/) | 7.13.4 [Elasticsearch Node.js client](https://www.npmjs.com/package/@elastic/elasticsearch/v/7.13.0) | 7.13.0 -Clients exist for a wide variety of languages, so if you test a client and verify that it works, please [submit a PR](https://github.com/opensearch-project/documentation-website/pulls) and add it to this table. +If you test a legacy client and verify that it works, please [submit a PR](https://github.com/opensearch-project/documentation-website/pulls) and add it to this table. {% comment %} diff --git a/_clients/python.md b/_clients/python.md index 879513ce..f2abffe5 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -23,6 +23,8 @@ Then import it like any other module: from opensearch import OpenSearch ``` +If you prefer to add the client manually or just want to examine the source code, see [opensearch-py on GitHub](https://github.com/opensearch-project/opensearch-py). + ## Sample code From c9728698934f57a36278d85314ab647407c06f90 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 26 Aug 2021 11:50:46 -0700 Subject: [PATCH 5/9] Link to pip, because why not --- _clients/python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/python.md b/_clients/python.md index f2abffe5..cdc7dc29 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -11,7 +11,7 @@ The OpenSearch Python client provides a more natural syntax for interacting with ## Setup -To add the client to your project, install it using pip: +To add the client to your project, install it using [pip](https://pip.pypa.io/): ```bash pip install From 50f3fa51d84c99f38580da1bb91523f63874a798 Mon Sep 17 00:00:00 2001 From: aetter Date: Fri, 10 Sep 2021 15:01:43 -0700 Subject: [PATCH 6/9] Update python.md --- _clients/python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/python.md b/_clients/python.md index cdc7dc29..bcb1ff93 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -14,7 +14,7 @@ The OpenSearch Python client provides a more natural syntax for interacting with To add the client to your project, install it using [pip](https://pip.pypa.io/): ```bash -pip install +pip install opensearch ``` Then import it like any other module: From 65f333d038325af731ff13dcae6e45f400d5398b Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 21 Sep 2021 13:40:38 -0700 Subject: [PATCH 7/9] Update python.md --- _clients/python.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/_clients/python.md b/_clients/python.md index bcb1ff93..9ce68bca 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -8,19 +8,23 @@ nav_order: 70 The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests with raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. +{% comment %} +`opensearch-py` is the lower-level of the two Python clients. If you want a general client for assorted operations, it's a great choice. If you want a higher-level client strictly for indexing and search operations, consider [opensearch-dsl-py]({{site.url}}{{site.baseurl}}/clients/python-dsl/). +{% endcomment %} + ## Setup To add the client to your project, install it using [pip](https://pip.pypa.io/): ```bash -pip install opensearch +pip install opensearch-py ``` Then import it like any other module: ```python -from opensearch import OpenSearch +from opensearchpy import OpenSearch ``` If you prefer to add the client manually or just want to examine the source code, see [opensearch-py on GitHub](https://github.com/opensearch-project/opensearch-py). @@ -29,7 +33,7 @@ If you prefer to add the client manually or just want to examine the source code ## Sample code ```python -from opensearch import OpenSearch +from opensearchpy import OpenSearch host = 'localhost' port = 9200 @@ -55,7 +59,7 @@ client = OpenSearch( ) # Create an index with non-default settings. -index_name = 'python-test-index3' +index_name = 'python-test-index' index_body = { 'settings': { 'index': { From 66ca05e7145c266b792938b461c686a964156566 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 21 Sep 2021 13:56:25 -0700 Subject: [PATCH 8/9] Update links --- _clients/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_clients/index.md b/_clients/index.md index 3880a3bb..d920e16a 100644 --- a/_clients/index.md +++ b/_clients/index.md @@ -15,8 +15,8 @@ For example, a 1.0.0 client works with an OpenSearch 1.1.0 cluster, but might no * [OpenSearch Java client]({{site.url}}{{site.baseurl}}/clients/java/) * [OpenSearch Python client]({{site.url}}{{site.baseurl}}/clients/python/) -* [OpenSearch JavaScript (Node.js) client]({{site.url}}{{site.baseurl}}/clients/nodejs/) -* [OpenSearch Go client]({{site.url}}{{site.baseurl}}/clients/golang/) +* [OpenSearch JavaScript (Node.js) client]({{site.url}}{{site.baseurl}}/clients/javascript/) +* [OpenSearch Go client]({{site.url}}{{site.baseurl}}/clients/go/) ## Legacy clients From ab00a055490e09d13d5b45c5a5e682e8465f1002 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 30 Sep 2021 13:48:32 -0700 Subject: [PATCH 9/9] Comment out Java for now --- _clients/index.md | 2 ++ _clients/python.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/_clients/index.md b/_clients/index.md index d920e16a..2f3513dd 100644 --- a/_clients/index.md +++ b/_clients/index.md @@ -13,7 +13,9 @@ OpenSearch provides clients for several popular programming languages, with more For example, a 1.0.0 client works with an OpenSearch 1.1.0 cluster, but might not support any non-breaking API changes in OpenSearch 1.1.0. A 1.2.0 client works with the same cluster, but might allow you to pass unsupported options in certain functions. We recommend using the same version for both, but if your tests pass after a cluster upgrade, you don't necessarily need to upgrade your clients immediately. +{% comment %} * [OpenSearch Java client]({{site.url}}{{site.baseurl}}/clients/java/) +{% endcomment %} * [OpenSearch Python client]({{site.url}}{{site.baseurl}}/clients/python/) * [OpenSearch JavaScript (Node.js) client]({{site.url}}{{site.baseurl}}/clients/javascript/) * [OpenSearch Go client]({{site.url}}{{site.baseurl}}/clients/go/) diff --git a/_clients/python.md b/_clients/python.md index 9ce68bca..10a856a2 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -6,7 +6,7 @@ nav_order: 70 # Python client -The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests with raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. +The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. {% comment %} `opensearch-py` is the lower-level of the two Python clients. If you want a general client for assorted operations, it's a great choice. If you want a higher-level client strictly for indexing and search operations, consider [opensearch-dsl-py]({{site.url}}{{site.baseurl}}/clients/python-dsl/).