diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a8d9bc7..a455f0e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,9 +11,10 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - Added support for the security plugin ([#399](https://github.com/opensearch-project/opensearch-py/pull/399)) - Compatibility with OpenSearch 2.1.0 - 2.6.0 ([#381](https://github.com/opensearch-project/opensearch-py/pull/381)) - Added 'allow_redirects' parameter in perform_request function for RequestsHttpConnection ([#401](https://github.com/opensearch-project/opensearch-py/pull/401)) -- Enhanced YAML test runner to use OpenSearch rest-api-spec YAML tests ([#414](https://github.com/opensearch-project/opensearch-py/pull/414) +- Enhanced YAML test runner to use OpenSearch rest-api-spec YAML tests ([#414](https://github.com/opensearch-project/opensearch-py/pull/414)) - Added `Search#collapse` ([#409](https://github.com/opensearch-project/opensearch-py/issues/409)) - Added support for the ISM API ([#398](https://github.com/opensearch-project/opensearch-py/pull/398)) +- Added new guide: `snapshot.md` for Snapshot API. ([#429](https://github.com/opensearch-project/opensearch-py/pull/429)) ### Changed - Upgrading pytest-asyncio to latest version - 0.21.0 ([#339](https://github.com/opensearch-project/opensearch-py/pull/339)) - Fixed flaky CI tests by replacing httpbin with a simple http_server ([#395](https://github.com/opensearch-project/opensearch-py/pull/395)) diff --git a/USER_GUIDE.md b/USER_GUIDE.md index 568a6c46..80ef1f34 100644 --- a/USER_GUIDE.md +++ b/USER_GUIDE.md @@ -35,6 +35,7 @@ - [Pre-requisites to use `AWSV4SignerAuth`](#pre-requisites-to-use-awsv4signerauth) - [Using IAM authentication with an async client](#using-iam-authentication-with-an-async-client) - [Using Kerberos](#using-kerberos) + - [Learn more about other guides](#learn-more) # User guide of OpenSearch Python client @@ -686,3 +687,12 @@ client = OpenSearch( health = client.cluster.health() ``` +## Learn more about other guides + +[Index Lifecycle](guides/index_lifecycle.md): This guide covers OpenSearch Python Client API actions for Index Lifecycle. You'll learn how to create, read, update, and delete indices in your OpenSearch cluster. We will also leverage index templates to create default settings and mappings for indices of certain patterns. + +[Search](guides/search.md): OpenSearch provides a powerful search API that allows you to search for documents in an index. The search API supports a number of parameters that allow you to customize the search operation. In this guide, we will explore the search API and its parameters. + +[Snapshot Actions](guides/snapshot.md): In this guide, we will look at some snapshot actions that allow you to manage and work with snapshots of your indices. + +Feel free to click on the links to access the respective guides and explore more about each topic. \ No newline at end of file diff --git a/guides/snapshot.md b/guides/snapshot.md new file mode 100644 index 00000000..cd5fc129 --- /dev/null +++ b/guides/snapshot.md @@ -0,0 +1,108 @@ +# Snapshot Actions +In this guide, we will look at some snapshot actions that allow you to manage and work with snapshots of your indices. + + +## Setup +Let's create a client instance, and an index named `movies`: +```python +from opensearchpy import OpenSearch + +client = OpenSearch( + hosts=['https://admin:admin@localhost:9200'], + use_ssl=True, + verify_certs=False +) + +print(client.info()) # Check server info and make sure the client is connected +client.indices.create(index='movies') +``` +## API Actions +### Create Snapshot Repository +Before taking a snapshot, you need to create a snapshot repository to store the snapshots. You can use the `create_repository` API action for this purpose. The following example creates a snapshot repository named `my_repository`: + +```python +repo_body = { + "type": "fs", # Replace 'fs' with the appropriate repository type + "settings": { + "location": "/path/to/repo", + } +} +client.snapshot.create_repository(repository='my_repository', body=repo_body) +``` + +### Create Snapshot +To create a snapshot of an index, you can use the `create` method from the `snapshot` API. The following example creates a snapshot named `my_snapshot` for the movies index: + +```python +client.snapshot.create(repository='my_repository', snapshot='my_snapshot', body={"indices": "movies"}) +``` + +### Verify Snapshot Repository +The `verify_repository` API action allows you to verify a snapshot repository. Verifying a repository ensures that it is accessible and operational, but it does not validate the integrity of the snapshots stored within the repository. The following example verifies `my_repository`: + +```python +response = client.snapshot.verify_repository(repository='my_repository') +``` + +### Delete Snapshot +To delete a specific snapshot, use the `delete` API action: + +```python +client.snapshot.delete(repository='my_repository', snapshot='my_snapshot') +``` +### Restore Snapshot +To restore a snapshot and recreate the indices, mappings, and data, you can use the `restore` method. The following example restores the `my_snapshot` snapshot: + +```python +response = client.snapshot.restore(repository='my_repository', snapshot='my_snapshot') +``` + +### Get Snapshot Status +To check the status of a snapshot, you can use the `status` method. + +```python +response = client.snapshot.status(repository='my_repository', snapshot='my_snapshot') +``` + +### Clone Snapshot +You can clone an existing snapshot to create a new snapshot with the same contents. The `clone` operation allows you to create multiple copies of a snapshot, which can be useful for backup retention or creating snapshots for different purposes. The following example clones a snapshot named `my_snapshot` to create a new snapshot named `my_snapshot_clone`: + +```python +client.snapshot.clone( + repository='my_repository', + snapshot='my_snapshot', + target_snapshot='my_snapshot_clone' +) +``` +## Get Snapshot +To retrieve information about a specific snapshot, you can use the `get` API action. It provides metadata such as the snapshot's status, indices included in the snapshot, and the timestamp when the snapshot was taken. The following example retrieves information about the `my_snapshot`: + +```python +response = client.snapshot.get( + repository='my_repository', + snapshot='my_snapshot' +) +``` + +## Get Repository +To retrieve information about a snapshot repository, you can use the `get_repository` API action. It provides details about the configured repository, including its type and settings. The following example retrieves information about the `my_repository`: + +```python +response = client.snapshot.get_repository(repository='my_repository') +``` + +## Repository Analyze +The `repository_analyze` API action allows you to analyze a snapshot repository for correctness and performance. It checks for any inconsistencies or corruption in the repository. The following example performs a repository analysis on `my_repository`: + +```python +response = client.snapshot.repository_analyze(repository='my_repository') +``` + +## Cleanup + +Finally, let's delete the `movies` index and clean up all the snapshots and the repository: +```python +client.indices.delete(index='movies') +client.snapshot.delete(repository='my_repository', snapshot='my_snapshot') +client.snapshot.delete_repository(repository='my_repository') +``` \ No newline at end of file