Elasticsearch

If you’re new to Unstructured, read this note first.

Before you can create a source connector, you must first sign in to your Unstructured account:

• If you do not already have an Unstructured account, sign up for free. After you sign up, you are automatically signed in to your new Unstructured Let’s Go account, at https://platform.unstructured.io. To sign up for a Business account instead, contact Unstructured Sales, or learn more.
• If you already have an Unstructured Let’s Go, Pay-As-You-Go, or Business SaaS account and are not already signed in, sign in to your account at https://platform.unstructured.io. For other types of Business accounts, see your Unstructured account administrator for sign-in instructions, or email Unstructured Support at [e-mail].

After you sign in, the Unstructured user interface (UI) appears, which you use to create your source connector.

After you create the source connector, add it along with a destination connector to a workflow. Then run the worklow as a job. To learn how, try out the hands-on UI quickstart or watch the 4-minute video tutorial.

You can also create source connectors with the Unstructured API. Learn how.

If you need help, email Unstructured Support at [e-mail].

You are now ready to start creating a source connector! Keep reading to learn how.

Ingest your files into Unstructured from Elasticsearch.

The requirements are as follows.

• For the Unstructured UI 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
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
  

  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.

• 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.
  • 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?.

To create the source connector:

1. On the sidebar, click Connectors.
2. Click Sources.
3. Cick New or Create Connector.
4. Give the connector some unique Name.
5. In the Provider area, click Elasticsearch.
6. Click Continue.
7. Follow the on-screen instructions to fill in the fields as described later on this page.
8. Click Save and Test.

Fill in the following fields:

• Name (required): A unique name for this connector.
• Host (required): The endpoint URL for the target cluster.
• Index Name (required): The name of the target index in the cluster.
• API Key (required): The Elastic Cloud API key for the target cluster.