Skip to content

Latest commit

 

History

History
142 lines (113 loc) · 5.63 KB

README.md

File metadata and controls

142 lines (113 loc) · 5.63 KB
Raw

graphql-algolia-transformer

Pull requests are welcome! npm GitHub license

Description

Add Serverless search to your Amplify API with Aloglia using this transformer.

@algolia vs @searchable

I made this transformer because I didn't want the monthly costs for the Elasticsearch instances used by @searchable. Algolia is effortless to get started and is free for up to 10k records and searches per month which makes it perfect for MVPs. As your app grows, you should probably re-evaluate the pricing difference between Elasticsearch and Algolia but this point is probably when you reach ~500k records/searches. Also, Algolia comes with nice client-side search UIs that you can just drop into your app. An obvious downside to using Algolia instead of Elasticsearch is that it takes you outside of the AWS world but I think that it's worth the tradeoff.

Use

Install Transform

npm install graphql-algolia-transformer

Import Transform

/amplify/backend/api/<API_NAME>/transform.conf.json

{
    . . .
    "transformers": [
        . . .,
        "graphql-algolia-transformer"
    ]
}

Use @algolia directive

Append to target models

@algolia(
          fields?: {
            include?: [string],
            exclude?: [string]
          }, 
          settings: {
            forwardToReplicas?: Boolean, 
            requestOptions?: AWSJSON, 
            settings: AWSJSON,
          }, 
          functionName?: String, 
          roleName?: String
        }
)

type Blog @model {
  id: ID!
  name: String!
  posts: [Post] @connection(keyName: "byBlog", fields: ["id"])
}

type Post @model @algolia(fields:{include:["title"]}) @key(name: "byBlog", fields: ["blogID"]) {
  id: ID!
  title: String!
  blogID: ID!
  blog: Blog @connection(fields: ["blogID"])
  comments: [Comment] @connection(keyName: "byPost", fields: ["id"])
}

type Comment @model @key(name: "byPost", fields: ["postID", "content"]) {
  id: ID!
  postID: ID!
  post: Post @connection(fields: ["postID"])
  content: String!
}
  • You cannot specify include and exclude in the same fields parameter.
  • Declare Algolia settings https://www.algolia.com/doc/api-reference/api-methods/set-settings/#parameters
  • Double check your Algolia settings (if specified) because they arent's validated until they are used in the Lambda function and can lead to a tricky problem to track down. If you create an entry on a model with the @algolia directive and no index is made in Algolia, check the Lambda function logs.
  • The Algolia ObjectID is a concatenation of the DynamoDB keys for the object; PrimaryKey(:SortKey).
  • Automatically creates an index with the model name (e.g. post).

Example

Check out the schema for the searchable blog example.

Configure Project ID & API Keys

/amplify/backend/api/<API_NAME>/parameters.json

{
  . . .
  "AlgoliaProjectIdPost": "PROJECT_NAME",
  "AlgoliaAppIdPost": "APPID",
  "AlgoliaApiKeyPost": "APIKEY",
}

The AlgoliaProjectId is necessary to autogenerate unique functions, rolesn & indexes across projects (e.g. searchable Posts model for project 1 and searchable Posts model for project 2).

Unfortunately, you have to define these parameters for each model that has the @algolia directive. I can't declare the parameters in each stack because it complains about the parameters name conflicting. I also tried exporting them from CustomResources.json but couldn't get it to work. This is a good issue to work on if you want to contribute.

Push Changes

amplify push

Query

For querying the search indexes, use an Algolia search client.

How it works

This directive creates an individual Lambda function for each declaration and attaches a DynamoDB stream from the respective table to the function. On receiving a stream, the function filters the fields as specified, formats the record into an Algolia payload and updates the Algolia index with the model name (if it doesn't exist, it creates it).

Contribute

Contributions are more than welcome!

Please feel free to create, comment and of course solve some of the issues. To get started you can also go for the easier issues marked with the good first issue label if you like.

Development

Algolia Lambda

  • npm run lambda uses SAM to invoke the Lambda function. You need to supply an App ID and API Key in template.yaml.
  • Modify the event you are sending in events/event.json.

Transformer

  • Initialize an amplify project and add an API
  • Import the transformer with the absolute path
// amplify/backend/api/<API_NAME>/transform.conf.json
{
    ...
    "transformers": [
        "file:///absolute/path/to/graphql-algolia-transform/"
    ]
}
  • Rebuild the transformer with npm run build.
  • amplify api gql-compile lets you check the stack outputs without having to go through the lengthy push process.
  • Check amplify/backend/api/<API>/build/stacks/AlgoliaStack<MODEL> for expected outputs.

License

The MIT License

Credits

The graphql-algolia-transformer library is maintained by Chris Finn The Finnternet.

Based on graphql-elasticsearch-transformer