{"id":20611909,"url":"https://github.com/jimmyn/aws-elasticsearch-model","last_synced_at":"2026-04-16T16:37:50.023Z","repository":{"id":39165250,"uuid":"232058248","full_name":"jimmyn/aws-elasticsearch-model","owner":"jimmyn","description":"Simplifies AWS Elasticsearch Service integration into serverless applications built with AWS Lambda","archived":false,"fork":false,"pushed_at":"2023-02-03T03:24:51.000Z","size":1013,"stargazers_count":2,"open_issues_count":16,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-16T20:36:26.740Z","etag":null,"topics":["aws-elasticsearch","aws-lambda","elasticsearch","serverless"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jimmyn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-06T08:37:01.000Z","updated_at":"2022-06-01T14:30:02.000Z","dependencies_parsed_at":"2023-02-03T10:31:47.880Z","dependency_job_id":null,"html_url":"https://github.com/jimmyn/aws-elasticsearch-model","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmyn%2Faws-elasticsearch-model","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmyn%2Faws-elasticsearch-model/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmyn%2Faws-elasticsearch-model/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmyn%2Faws-elasticsearch-model/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jimmyn","download_url":"https://codeload.github.com/jimmyn/aws-elasticsearch-model/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242259946,"owners_count":20098429,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-elasticsearch","aws-lambda","elasticsearch","serverless"],"created_at":"2024-11-16T10:22:34.750Z","updated_at":"2026-04-16T16:37:44.989Z","avatar_url":"https://github.com/jimmyn.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS Elasticsearch Model\nA small library that simplifies [AWS Elasticsearch Service](https://aws.amazon.com/elasticsearch-service/) integration into serverless applications build with AWS Lambda\n\n## Install\n```\nnpm i aws-elasticsearch-model --save\n```\nor\n```\nyarn add aws-elasticsearch-model\n```\n\n## Intitialize\n\n```typescript\nimport AWS from 'aws-sdk';\nimport {ElasticModel} from 'aws-elasticsearch-model';\n\n/*\n ElasticModel uses aws-sdk's default behaviour to obtain region + credentials from your environment. \n If you would like to set these manually, you can set them on aws-sdk:\n*/\nAWS.config.update({region: 'eu-west-1'});\n\nconst elasticModel = new ElasticModel({\n  host: 'https://my-aws-elasticsearch-domain.eu-west-1.es.amazonaws.com',\n  index: 'users'\n});\n\n```\n\n## Index your data\nElasticModel will automatically create [elasticsearch index](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html) if missing\n\n```typescript\nconst users = [\n  {\n    id: '554d9d95-b40b-4ddc-9fa9-ed3eb8b5c591',\n    email: 'Vidal45@gmail.com',\n    name: 'Beverly_Mayer18'\n  },\n  {\n    id: 'cf39921a-41ce-49cc-b034-13fb1508c726',\n    email: 'Marcel16@yahoo.com',\n    name: 'Petra70'\n  },\n  {\n    id: '81ab442a-b693-47e5-b9e1-6807cbb7978e',\n    email: 'Howell73@gmail.com',\n    name: 'Carlotta_Kuhic37'\n  }\n];\n\nconst result = await elasticModel.bulkIndex(users);\n```\n\n## Sync your index with DynamoDB table using Lambda\nQuite often DynamoDB table is used as a source of truth to store data and Elasticsearch is used to provide advanced search capabilities. In this case a Lambda function is required to sync data between DynamoDB table and Elasticsearch index\n\nAttach this lambda handler to your DynamoDB table and it will sync all the data changes with Elasticsearch\n\n```typescript\nimport {DynamoDBStreamEvent} from 'aws-lambda';\nimport {ElasticModel} from 'aws-elasticsearch-model';\n\nconst elasticModel = new ElasticModel({\n  host: 'https://my-aws-elasticsearch-domain.eu-west-1.es.amazonaws.com',\n  index: 'users'\n});\n\nexport const handler = async (event: DynamoDBStreamEvent) =\u003e {\n  return elasticModel.indexFromDynamoDBStream(event);\n};\n\n```\n\nYour lambda function needs to have a role attached to it that allows to access your Elasticsearch instance\n\n```\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Action\": [\n        \"es:ESHttpPost\",\n        \"es:ESHttpPut\",\n        \"es:ESHttpDelete\"\n      ],\n      \"Resource\": \"arn:aws:es:AWS_REGION:AWS_ACCOUNT_ID:domain/my-aws-elasticsearch-domain/*\",\n      \"Effect\": \"Allow\"\n    }\n  ]\n}\n```\n\n## Query your data\n[queryBuilder](src/index.ts#L145) method will return a chainable function that allows easily build complex queries for elasticsearch with a simple, predictable api.\n\nIt uses [bodybuilder](https://github.com/danpaz/bodybuilder) package by [Daniel Paz-Soldan](https://github.com/danpaz)\n\nTo get full builder api check the [docs here](https://bodybuilder.js.org/docs/)\n\nTo execute the query call `query.exec()` at the end\n\n```typescript\nconst query = elasticModel\n  .queryBuilder()\n  .orFilter('term', 'email', 'Vidal45@gmail.com')\n  .orFilter('term', 'email', 'Marcel16@yahoo.com');\n\nconst result = await query.exec();\n```\n\n```typescript\n{\n  items: [\n    {\n      id: '554d9d95-b40b-4ddc-9fa9-ed3eb8b5c591',\n      email: 'Vidal45@gmail.com',\n      name: 'Beverly_Mayer18'\n    },\n    {\n      id: 'cf39921a-41ce-49cc-b034-13fb1508c726',\n      email: 'Marcel16@yahoo.com',\n      name: 'Petra70'\n    }\n  ],\n  total: 2,\n  raw: {...} // raw elasticsearch response\n}\n```\n\nYou can also run a search query directly. The query above is equivalent to:\n\n```typescript\nconst result = await elasticModel.search({\n  query: {\n    bool: {\n      filter: {\n        bool: {\n          should: [\n            {\n              term: {\n                email: 'Vidal45@gmail.com'\n              }\n            },\n            {\n              term: {\n                email: 'Marcel16@yahoo.com'\n              }\n            }\n          ]\n        }\n      }\n    }\n  }\n});\n```\n\n## Use custom mapping and index settings\nBy default Elasticsearch will try to guess your data structure but you can provide your own index mapping to improve search performance.\n\n```typescript\nconst elasticModel = new ElasticModel({\n  host: 'https://my-aws-elasticsearch-domain.eu-west-1.es.amazonaws.com',\n  index: 'users',\n  settings: {\n    analysis: {\n      analyzer: {\n        email: {\n          type: 'custom',\n          tokenizer: 'uax_url_email'\n        }\n      }\n    }\n  },\n  mapping: {\n    id: {\n      type: 'keyword'\n    },\n    email: {\n      type: 'text',\n      analyzer: 'email'\n    },\n    name: {\n      type: 'text'\n    }\n  }\n});\n```\n\nRead more about [mappings](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html) and [settings](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#index-modules-settings)\n\n## Use custom `id` field\nBy default ElasticModel will use `id` field in your data to provide unique `id` to Elasticsearch but it can be customized.\n\n```typescript\nconst elasticModel = new ElasticModel({\n  host: 'https://my-aws-elasticsearch-domain.eu-west-1.es.amazonaws.com',\n  index: 'users',\n  idField: 'userId'\n});\n```\n\nWhen you sync your data with DynamoDB `DynamoDBStreamEvent` event provides `Keys` object that will contain a composite hash key of your item. For example if you have `hashKey: 'userId', rangeKey: 'createdAt'` by default only `userId` filed will be selected as `id` (if it is specified in config).\n\nThis behaviour can be customized: \n\n```typescript\nexport const handler = async (event: DynamoDBStreamEvent) =\u003e {\n  return elasticModel.indexFromDynamoDBStream(event, keys =\u003e {\n    // keys: {userId, createdAt}\n    // use base64 encoded userId\n    return new Buffer(keys.userId).toString('base64');\n  });\n};\n```\n\n## Exclude fields\nTo completely exclude fields from Elasticsearch you can provide `excludedFields` option. This option will remove the field before data is submitted.\n\n```typescript\nconst elasticModel = new ElasticModel({\n  host: 'https://my-aws-elasticsearch-domain.eu-west-1.es.amazonaws.com',\n  index: 'users',\n  excludedFields: ['email']\n});\n```\nIf you want field value to be stored but not indexed or available for search you can set `index: false` parameter in mapping\n\n```typescript\nconst elasticModel = new ElasticModel({\n  host: 'https://my-aws-elasticsearch-domain.eu-west-1.es.amazonaws.com',\n  index: 'users',\n  mapping: {\n    id: {\n      type: 'keyword'\n    },\n    email: {\n      index: false,\n      type: 'text'\n    },\n    name: {\n      type: 'text'\n    }\n  }\n});\n```\n\n## Access Elasticsearch client\nElasticModel provides direct access to [elasticsearch client](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/16.x/index.html). You can access client instance as `elasticModel.client`\n\n## Available config options\nYou can find all config options [here](src/index.ts#L72)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimmyn%2Faws-elasticsearch-model","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjimmyn%2Faws-elasticsearch-model","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimmyn%2Faws-elasticsearch-model/lists"}