Elasticsearch

​

Requirements

• For the Unstructured Pipelines or the Unstructured API, only Elastic Cloud instances are supported.
• For Unstructured Ingest, Elastic Cloud instances and self-manged Elasticsearch instances are supported.
• For Elastic Cloud, you will need an Elastic Cloud service instance.
• For self-managed Elasticsearch, you will need a self-managed Elasticsearch instance.
• You will need the name of the index on the instance. For the destination connector, if you need to create an index, you can use for example the following curl command. Replace the following placeholders:
  • Replace <host>:<port> with the instance’s host identifier and port number.
  • Replace one of the following, and remove the other:
    • For an instance’s user and password combination, replace <username> with your Elasticsearch or Elastic Cloud instance’s user name, replace <password> with your password, and then remove --user "Authorization: ApiKey <your-api-key>".
    • For an Elastic Cloud API key, replace <your-api-key> with your Elastic Cloud API key, and then remove --user "<username>:<password>".
  • Replace <index-name> with the name of the new index on the instance.
  • Replace <index-schema> with the schema for the index. A schema is optional; see the explanation following this curl command for more information.
  curl --request PUT "<host>:<port>/<index-name>" \
  --user "<username>:<password>" \
  --user "Authorization: ApiKey <your-api-key>" \
  [--header "Content-Type: application/json" \
  --data '<index-schema>']
  
  To learn more, see Create index and Get index. For the destination connector, the index does not need to contain a schema beforehand. If Unstructured encounters an index without a schema, Unstructured will automatically create a compatible schema for you before inserting items into the index. Nonetheless, to reduce possible schema compatibility issues, Unstructured recommends that you create a schema that is compatible with Unstructured’s schema. Unstructured cannot provide a schema that is guaranteed to work in all circumstances. This is because these schemas will vary based on your source files’ types; how you want Unstructured to partition, chunk, and generate embeddings; any custom post-processing code that you run; and other factors. For objects in the metadata field that Unstructured produces and that you want to store in an Elasticsearch or Elastic Cloud index, you must create fields in your index’s schema that follows Unstructured’s metadata field naming convention. For example, if Unstructured produces a metadata field with the following child objects:
  "metadata": {
    "is_extracted": "true",
    "coordinates": {
      "points": [
        [
          134.20055555555555,
          241.36027777777795
        ],
        [
          134.20055555555555,
          420.0269444444447
        ],
        [
          529.7005555555555,
          420.0269444444447
        ],
        [
          529.7005555555555,
          241.36027777777795
        ]
      ],
      "system": "PixelSpace",
      "layout_width": 1654,
      "layout_height": 2339
    },
    "filetype": "application/pdf",
    "languages": [
      "eng"
    ],
    "page_number": 1,
    "image_mime_type": "image/jpeg",
    "filename": "realestate.pdf",
    "data_source": {
      "url": "file:///home/etl/node/downloads/00000000-0000-0000-0000-000000000001/7458635f-realestate.pdf",
      "record_locator": {
        "protocol": "file",
        "remote_file_path": "file:///home/etl/node/downloads/00000000-0000-0000-0000-000000000001/7458635f-realestate.pdf"
      }
    },
    "entities": {
      "items": [
        {
          "entity": "HOME FOR FUTURE",
          "type": "ORGANIZATION"
        },
        {
          "entity": "221 Queen Street, Melbourne VIC 3000",
          "type": "LOCATION"
        }
      ],
      "relationships": [
        {
          "from": "HOME FOR FUTURE",
          "relationship": "based_in",
          "to": "221 Queen Street, Melbourne VIC 3000"
        }
      ]
    }
  }
  
  You can adapt the following index schema example for your own needs. Note that outside of metadata, the following fields are required by Unstructured whenever you create your own index schema:
  • element_id
  • record_id, which is required by Unstructured for intelligent record updates.
  • type, which is not required, but highly recommended.
  • text
  • embeddings if embeddings are generated; make sure to set dims to the same number of dimensions as the embedding model generates.
  {
    "mappings": {
      "properties": {
        "element_id": {
          "type": "keyword"
        },
        "record_id": {
          "type": "text"
        },
        "text": {
          "type": "text"
        },
        "type": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 256
            }
          }
        },
        "embeddings": {
          "type": "dense_vector",
          "dims": 1536,
          "index": true,
          "similarity": "cosine"
        },
        "metadata": {
          "properties": {
            "is_extracted": {
              "type": "boolean"
            },
            "coordinates-points": {
              "type": "float"
            },
            "coordinates-system": {
              "type": "text",
              "fields": {
                "keyword": {
                  "type": "keyword",
                  "ignore_above": 256
                }
              }
            },
            "coordinates-layout_width": {
              "type": "long"
            },
            "coordinates-layout_height": {
              "type": "long"
            },
            "filetype": {
              "type": "keyword"
            },
            "languages": {
              "type": "keyword"
            },
            "page_number": {
              "type": "integer"
            },
            "image_mime_type": {
              "type": "keyword"
            },
            "filename": {
              "type": "keyword"
            },
            "data_source-url": {
              "type": "keyword"
            },
            "data_source-record_locator-protocol": {
              "type": "keyword"
            },
            "data_source-record_locator-remote_file_path": {
              "type": "keyword"
            },
            "entities-items": {
              "properties": {
                "entity": {
                  "type": "text",
                  "fields": {
                    "keyword": {
                      "type": "keyword",
                      "ignore_above": 256
                    }
                  }
                },
                "type": {
                  "type": "text",
                  "fields": {
                    "keyword": {
                      "type": "keyword",
                      "ignore_above": 256
                    }
                  }
                }
              }
            },
            "entities-relationships": {
              "properties": {
                "from": {
                  "type": "text",
                  "fields": {
                    "keyword": {
                      "type": "keyword",
                      "ignore_above": 256
                    }
                  }
                },
                "relationship": {
                  "type": "text",
                  "fields": {
                    "keyword": {
                      "type": "keyword",
                      "ignore_above": 256
                    }
                  }
                },
                "to": {
                  "type": "text",
                  "fields": {
                    "keyword": {
                      "type": "keyword",
                      "ignore_above": 256
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
  
  The record_id, element_id, and id fields are closely related, but each has a distinct purpose. For more information, see How connectors use record IDs, element IDs, and IDs.
  See also:
  • An Introduction to Elasticsearch Mapping
  • Explicit mapping
  • Dynamic field mapping
  • Unstructured document elements and metadata
• For Elastic Cloud, you will need the Elastic Cloud service instance’s API key. If you are using Unstructured Ingest, you will also need the instance’s Cloud ID. To get these, see your Elasticsearch Service web console or Elastic Cloud API keys.
  When generating an Elastic Cloud service instance’s API key through the Elasticsearch Service web console, be sure after you click Create API key to select Encoded to get the API key’s value. (The Encoded API key value is the Base64 encoding of the UTF-8 representation of the API key’s ID and key value joined by a colon [:].)
• For self-managed Elasticsearch, you will need:
  • The self-managed instance’s hostname and port number. See Networking.
  • If you’re using basic authentication to the self-managed instance, the user’s name and password.
  • If you’re using token-based authentication to the self-managed instance, the bearer token or API key for the instance. See Token-based authentication services and Create API key.
    When generating an API key for a self-managed Elasticsearch instance by calling POST /_security/api_key, be sure to use the encoded value in the response payload. (This encoded value is the Base64 encoding of the UTF-8 representation of the payload’s id and api_key values joined by a colon [:]). Do not use the api_key value by itself.
  • If you’re using certificate authentication to the self-managed instance, the path to the Certificate Authority (CA) file on the instance, and the certificate fingerprint. See SSL certificate API and Where can I see my Certificate Fingerprint?.

​

Examples

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import CreateDestinationRequest
from unstructured_client.models.shared import CreateDestinationConnector

with UnstructuredClient(api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")) as client:
    response = client.destinations.create_destination(
        request=CreateDestinationRequest(
            create_destination_connector=CreateDestinationConnector(
                name="<name>",
                type="elasticsearch",
                config={
                    "hosts": ["<host-url>"],
                    "es_api_key": "<es-api-key>",
                    "index_name": "<index-name>"
                }
            )
        )
    )

    print(response.destination_connector_information)

​

Configuration settings

​

Learn more

•   Finding Needles in a Haystack: PII Detection at Scale with Unstructured, Box, and Elasticsearch