diff --git a/_api-reference/document-apis/index-document.md b/_api-reference/document-apis/index-document.md index ec1664bc44..3460fc1d50 100644 --- a/_api-reference/document-apis/index-document.md +++ b/_api-reference/document-apis/index-document.md @@ -11,7 +11,7 @@ redirect_from: **Introduced 1.0** {: .label .label-purple} -Before you can search for data, you must first add documents. This operation adds a single document to your index. +You can use the `Index document` operation to add a single document to your index. ## Example @@ -33,6 +33,53 @@ PUT /_create/<_id> POST /_create/<_id> ``` +- PUT adds or updates documents in the index with a specified ID. Used for controlled document creation or updates. +- POST adds documents with auto-generated IDs to the index. Useful for adding new documents without specifying IDs. +- `_create` is a type identifier indicating that document creation should only occur if the document with the specified ID doesn't already exist. +- `` represents the name of the index to which the document will be added. +- `<_id>` represents the unique identifier of the document. + +## Adding a sample index + +Sample data can be added to the index with curl commands in the terminal or through the API. + +To test the Document APIs, add a document by following these steps: +1. Open OpenSearch Dashboards. +2. Navigate to the actions menu. +3. In the **Management** section, choose **Dev Tools**. +4. Enter a command, and then select the green triangle play button to send the request. The following are some example commands. + +### Create a sample-index +```json +PUT /sample-index +``` +{% include copy-curl.html %} + +### Example PUT request + +```json +PUT /sample_index/_doc/1 +{ + "name": "Example", + "price": 29.99, + "description": "To be or not to be, that is the question" +} +``` +{% include copy-curl.html %} + +### Example POST request + +```json +POST /sample_index/_doc +{ + "name": "Another Example", + "price": 19.99, + "description": "We are such stuff as dreams are made on" +} + +``` +{% include copy-curl.html %} + ## URL parameters In your request, you must specify the index you want to add your document to. If the index doesn't already exist, OpenSearch automatically creates the index and adds in your document. All other URL parameters are optional. diff --git a/_security/access-control/document-level-security.md b/_security/access-control/document-level-security.md index be5fe7e0da..08de85bbf7 100644 --- a/_security/access-control/document-level-security.md +++ b/_security/access-control/document-level-security.md @@ -4,35 +4,35 @@ title: Document-level security parent: Access control nav_order: 85 redirect_from: - - /security/access-control/document-level-security/ - - /security-plugin/access-control/document-level-security/ +- /security/access-control/document-level-security/ +- /security-plugin/access-control/document-level-security/ --- -# Document-level security (DLS) - -Document-level security lets you restrict a role to a subset of documents in an index. -For more information about OpenSearch users and roles, see the [documentation](https://opensearch.org/docs/latest/security/access-control/users-roles/#create-roles). - -Use the following steps to get started with document-level and field-level security: -1. Open OpenSearch Dashboards. -2. Choose **Security** > **Roles**. -3. Select **Create Role** and provide a name for the role. -4. Review the **Index permissions** section and any necessary [index permissions](https://opensearch.org/docs/latest/security/access-control/permissions/) for the role. -5. Add document-level security, with the addition of a domain-specific language (DSL) query in the `Document level security - optional` section. A typical request sent to the `_search` API includes `{ "query": { ... } }` around the query, but with document-level security in OpenSearch Dashboards, you only need to specify the query itself. For example, the following DSL query specifies that for the new role to have access to a document, the query's `genres` field must include `Comedy`: - - ```json - { - "bool": { - "must": { - "match": { - "genres": "Comedy" - } - } - } - } - ``` - - - ![Document- and field-level security screen in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/security-dls.png) +# Document-level security +Document-level security lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index Permissions** section, shown in the following image. + +![Document- and field-level security screen in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/security-dls.png) + + +## Simple roles + +Document-level security uses OpenSearch query domain-specific language (DSL) to define which documents a role grants access to. In OpenSearch Dashboards, choose an index pattern and provide a query in the **Document-level security** section: + +```json +{ + "bool": { + "must": { + "match": { + "genres": "Comedy" + } + } + } +} +``` + +This query specifies that for the role to have access to a document, its `genres` field must include `Comedy`. + +A typical request sent to the `_search` API includes `{ "query": { ... } }` around the query, but in this case, you only need to specify the query itself. ## Updating roles by accessing the REST API