Routing functions

Routing functions allow you to dynamically direct messages to different destinations based on the content of the message. This is useful for:

Interacting with REST APIs which assign each record its own resource path
Using different HTTP methods based on the change action
Implementing custom routing logic based on record contents
Customizing message routing for various messaging systems

How routing functions work

When you create a routing function, you define an Elixir function that returns routing information. Sequin will use this information to determine the destination for each message. For each message, your routing function receives the same parameters as a transform function and must return a map containing the sink-specific routing information:

def route(action, record, changes, metadata) do
  # Return a map with sink-specific routing parameters
  %{
    # Sink-specific routing parameters
  }
end

In general, some details of how the message is processed will be static and fixed by the sink. Routing functions enable you to customize the behavior of a sink, but they are not intended to replace the idea of multiple sinks where necessary. For example, for the HTTP Webhook sink, the base URL is a static property - this improves batching and enables other performance optimizations such as connection pooling and request pipelining.

Sinks

Each sink type has different fields that can be routed:

Kafka sink

For Kafka, your routing function must return a map with these keys:

Key	Type	Description	Example
`topic`	String	The topic to publish to	`"users.created"`
`message_key`	String	The message key to publish to	`"users:123"`

HTTP Webhook sink

For HTTP webhooks, your routing function must return a map with these keys:

Key	Type	Description	Example
`method`	String	The HTTP method to use	`"POST"`, `"PUT"`, `"DELETE"`
`endpoint_path`	String	The path to append to your webhook base URL	`"/users/123"`

The endpoint_path you specify will be appended to the base URL of your webhook endpoint. For example, if your webhook endpoint is https://api.example.com and your routing function returns endpoint_path: "/users/123", the message will be sent to https://api.example.com/users/123.

Redis String sink

For Redis String, your routing function must return a map with these keys:

Key	Type	Description	Example
`key`	String	The key to use for the message	`"users:123"`

The key is used to determine the key in Redis where the message will be stored in the SET operation:

SET key value

Redis Stream sink

For Redis Stream, your routing function must return a map with these keys:

Key	Type	Description	Example
`stream_key`	String	The stream key to publish to	`"users"`

NATS sink

For NATS, your routing function must return a map with these keys:

Key	Type	Description	Example
`subject`	String	The subject to publish to	`"users.created"`

GCP PubSub sink

For GCP PubSub, your routing function must return a map with these keys:

Key	Type	Description	Example
`topic_id`	String	The topic ID to publish to	`"users.created"`

Elasticsearch sink

For Elasticsearch, your routing function must return a map with these keys:

Key	Type	Description	Example
`index_name`	String	The index to publish to	`"users"`

Typesense sink

For Typesense, your routing function must return a map with these keys:

Key	Type	Description	Example
`action`	String	The action to perform on the collection	`"index"`, `"delete"`
`collection_name`	String	The collection name to index into	`"users"`

Meilisearch sink

For Meilisearch, your routing function must return a map with these keys:

Key	Type	Description	Example
`action`	String	The action to perform on the collection	`"index"`, `"delete"`
`index_name`	String	The index to publish to	`"users"`

AWS SQS sink

For AWS SQS, your routing function must return a map with these keys:

Key	Type	Description	Example
`queue_url`	String	The queue URL to publish to	`"https://sqs.us-east-1.amazonaws.com/123456789012/users"`

AWS Kinesis sink

For AWS Kinesis, your routing function must return a map with these keys:

Key	Type	Description	Example
`stream_arn`	String	The Kinesis stream ARN to publish to	`"arn:aws:kinesis:us-east-1:123456789012:stream/my-stream"`

S2 sink

For S2, your routing function must return a map with these keys:

Key	Type	Description	Example
`basin`	String	The S2 basin to publish to	`"my-basin"`
`stream`	String	The S2 stream to append records to	`"users"`

RabbitMQ sink

For RabbitMQ, your routing function must return a map with these keys:

Key	Type	Description	Example
`exchange`	String	The exchange to publish to	`"sequin"`
`routing_key`	String	The routing key to publish to	`"sequin.users.insert"`
`headers`	Map	AMQP headers to include	`%{"x-key" => "value"}`

Azure Event Hub sink

For Azure Event Hubs, your routing function must return a map with these keys:

Key	Type	Description	Example
`event_hub_name`	String	The Event Hub name to publish to	`"sequin.db.public.users"`

Common routing patterns

Routing to REST APIs

Route messages to RESTful endpoints based on record ID and action:

def route(action, record, changes, metadata) do
  endpoint_path = "/api/users/#{record["external_id"]}"

  method = case action do
    "insert" -> "POST"
    "update" -> "PUT"
    "delete" -> "DELETE"
    _ -> "POST"
  end

  %{
    method: method,
    endpoint_path: endpoint_path
  }
end

Content-based routing

Route messages based on their content:

def route(action, record, changes, metadata) do
  # Route high-priority messages to a different endpoint
  if record["priority"] == "high" do
    %{
      method: "POST",
      endpoint_path: "/api/priority-events"
    }
  else
    %{
      method: "POST",
      endpoint_path: "/api/events"
    }
  end
end

Testing routing functions

When creating or editing a routing function, you can test it with real data from your database. Sequin will capture recent events and show you the effective routing parameters for each message. “Effective” means that Sequin will show the routing parameters that will actually be used downstream, inclusive of any defaulting or validation which happens after your routing function runs.

Limitations and considerations

Routing can impact batching if your routing function generates different destinations for each message.

Function Transforms

Learn about function transforms and how to use them to modify your message content.

Messages reference

Learn about the different fields you can use in routing functions.

Sequin YAML config

Learn about configuring functions in your sequin.yaml file.

HTTP Webhooks

Learn more about configuring HTTP webhook destinations.

Get started

Sink setup guides

How-to guides

Concepts

Reference

Database setup guides

Tutorials

Routing functions

How routing functions work

Sinks

Kafka sink

HTTP Webhook sink

Redis String sink

Redis Stream sink

NATS sink

GCP PubSub sink

Elasticsearch sink

Typesense sink

Meilisearch sink

AWS SQS sink

AWS Kinesis sink

S2 sink

RabbitMQ sink

Azure Event Hub sink

Common routing patterns

Routing to REST APIs

Content-based routing

Testing routing functions

Limitations and considerations

Function Transforms

Messages reference

Sequin YAML config

HTTP Webhooks

​How routing functions work

​Sinks

​Kafka sink

​HTTP Webhook sink

​Redis String sink

​Redis Stream sink

​NATS sink

​GCP PubSub sink

​Elasticsearch sink

​Typesense sink

​Meilisearch sink

​AWS SQS sink

​AWS Kinesis sink

​S2 sink

​RabbitMQ sink

​Azure Event Hub sink

​Common routing patterns

​Routing to REST APIs

​Content-based routing

​Testing routing functions

​Limitations and considerations

​Related

Function Transforms

Messages reference

Sequin YAML config

HTTP Webhooks

How routing functions work

Sinks

Kafka sink

HTTP Webhook sink

Redis String sink

Redis Stream sink

NATS sink

GCP PubSub sink

Elasticsearch sink

Typesense sink

Meilisearch sink

AWS SQS sink

AWS Kinesis sink

S2 sink

RabbitMQ sink

Azure Event Hub sink

Common routing patterns

Routing to REST APIs

Content-based routing

Testing routing functions

Limitations and considerations

Related