Skip to main content
Version: 2.11

Router radixtree

what's libradixtree?#

libradixtree, adaptive radix trees implemented in Lua for OpenResty.

APISIX using libradixtree as route dispatching library.

How to use libradixtree in APISIX?#

This is Lua-OpenResty implementation library base on FFI for rax.

Let's take a look at a few examples and have an intuitive understanding.

1. Full match#


It will only match /blog/foo.

2. Prefix matching#


It will match the path with the prefix /blog/bar, eg: /blog/bar/a, /blog/bar/b, /blog/bar/c/d/e, /blog/bar etc.

3. Match priority#

Full match -> Deep prefix matching.

Here are the rules:

pathMatch result
/blog/barnot match

4. Different routes have the same uri#

When different routes have the same uri, you can set the priority field of the route to determine which route to match first, or add other matching rules to distinguish different routes.

Note: In the matching rules, the priority field takes precedence over other rules except uri.

  1. Different routes have the same uri and set the priority field

Create two routes with different priority values ​​(the larger the value, the higher the priority).

$ curl -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "upstream": {       "nodes": {           "": 1       },       "type": "roundrobin"    },    "priority": 3,    "uri": "/hello"}'
$ curl -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "upstream": {       "nodes": {           "": 1       },       "type": "roundrobin"    },    "priority": 2,    "uri": "/hello"}'



All requests only hit the route of port 1980.

  1. Different routes have the same uri and set different matching conditions

Here is an example of setting host matching rules:

$ curl -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "upstream": {       "nodes": {           "": 1       },       "type": "roundrobin"    },    "hosts": [""],    "uri": "/hello"}'
$ curl -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "upstream": {       "nodes": {           "": 1       },       "type": "roundrobin"    },    "hosts": [""],    "uri": "/hello"}'


$ curl -H 'host:'1980
$ curl -H 'host:'1981
$ curl{"error_msg":"404 Route Not Found"}

The host rule matches, the request hits the corresponding upstream, and the host does not match, the request returns a 404 message.

5. Parameter match#

When radixtree_uri_with_parameter is used, we can match routes with parameters.

For example, with configuration:

apisix:    router:        http: 'radixtree_uri_with_parameter'

route like


will match both /blog/dog and /blog/cat.

For more details, see

How to filter route by Nginx builtin variable#

Please take a look at radixtree-new, here is an simple example:

$ curl -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '{    "uri": "/index.html",    "vars": [        ["http_host", "==", ""],        ["cookie_device_id", "==", "a66f0cdc4ba2df8c096f74c9110163a9"],        ["arg_name", "==", "json"],        ["arg_age", ">", "18"],        ["arg_address", "~~", "China.*"]    ],    "upstream": {        "type": "roundrobin",        "nodes": {            "": 1        }    }}'

This route will require the request header host equal, request cookie key _device_id equal a66f0cdc4ba2df8c096f74c9110163a9 etc.

How to filter route by POST form attributes#

APISIX supports filtering route by POST form attributes with Content-Type = application/x-www-form-urlencoded.

We can define the following route:

$ curl -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '{    "methods": ["POST"],    "uri": "/_post",    "vars": [        ["post_arg_name", "==", "json"]    ],    "upstream": {        "type": "roundrobin",        "nodes": {            "": 1        }    }}'

The route will be matched when the POST form contains name=json.

How to filter route by GraphQL attributes#

APISIX supports filtering route by some attributes of GraphQL. Currently we support:

  • graphql_operation
  • graphql_name
  • graphql_root_fields

For instance, with GraphQL like this:

query getRepo {    owner {        name    }    repo {        created    }}
  • The graphql_operation is query
  • The graphql_name is getRepo,
  • The graphql_root_fields is ["owner", "repo"]

We can filter such route out with:

$ curl -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '{    "methods": ["POST"],    "uri": "/_graphql",    "vars": [        ["graphql_operation", "==", "query"],        ["graphql_name", "==", "getRepo"],        ["graphql_root_fields", "has", "owner"]    ],    "upstream": {        "type": "roundrobin",        "nodes": {            "": 1        }    }}'

To prevent spending too much time reading invalid GraphQL request body, we only read the first 1 MiB data from the request body. This limitation is configured via:

graphql:  max_size: 1048576

If you need to pass a GraphQL body which is larger than the limitation, you can increase the value in conf/config.yaml.