Filters

The ODIN CLI allows users to filter data using a flexible and powerful filter syntax. This is especially useful when working with large datasets, allowing you to extract exactly the information you need.

Basics#

You can set a filter using the --filter flag followed by the filter expression. If omitted, the command will return all resources. Resources are filtered on the server side, but depending on command it may also be filtered on the client side or even a combination of both.

The filter expression follows a straightforward structure of <field> <operator> <value>. The field can be any property in the dataset, and operators include basic comparison operators such as =, !=, >, <, >=, and <=. Filters can also be combined using logical operators AND, OR, and negated with NOT.

You can access nested fields using dot notation, and strings should be enclosed in quotes. Here’s an example using a basic filter:

--filter="serverConfig.name = 'Minecraft Production 2''

This filter will return all servers where the serverConfig.name is "Minecraft Production 2".

Supported Operators#

• =: Equal to
• !=: Not equal to
• >: Greater than
• <: Less than
• >=: Greater than or equal to
• <=: Less than or equal to
• ~ : Contains (for strings)

The ~ also allows usage of wildcards (*) for partial matches. For example:

--filter="serverConfig.name ~ 'Minecraft*'"

This filter will return all servers where the serverConfig.name starts with "Minecraft".

Combining Filters#

You can combine multiple conditions using AND and OR operators:

• AND: Both conditions must be true.
• OR: At least one condition must be true.

--filter="serverConfig.name = 'Minecraft Production 2' AND id > 100"

This filter will return all servers where the serverConfig.name is "Minecraft Production 2" and the id is greater than 100.

Negation with NOT#

You can negate conditions using the NOT operator. For example:

--filter="NOT (serverConfig.name = 'Minecraft Production 2')"

This will return all servers where the serverConfig.name is not "Minecraft Production 2".

Accessing Nested Properties#

You can filter based on nested properties using dot notation. For example, if you want to filter servers based on a nested property like serverConfig.name, you can do:

--filter="serverConfig.name = 'Minecraft Production 2'"

Here’s an example using the serverConfig object from a typical server JSON structure (just the interesting part is shown here):

{
  "id": 134,
  "serverConfig": {
    "name": "Minecraft Production 2",
    "status": "ready"
  }
}

This filter will return all servers with the serverConfig.name set to "Minecraft Production 2".

Examples#

Filtering Servers by Config#

odin fleet servers list --filter="serverConfig.status = 'ready' AND serverConfig.name = 'Minecraft Production 2'"

This filter will return servers that are ready and have the name "Minecraft Production 2".

Combining Logical Conditions#

odin fleet servers list --filter="(serverConfig.status = 'ready' AND serverConfig.name = 'Minecraft Production 2') OR id = 211"

This will return servers that either:

• Have a serverConfig.status of "ready" and a serverConfig.name of "Minecraft Production 2", or
• Have an id of 211.

Negating Conditions#

odin fleet servers list --filter="NOT (serverConfig.status = 'ready')"

This filter will return all servers where the serverConfig.status is not "ready".

Filtering by Ports#

If you need to filter based on the ports object in the server JSON, you can do so using nested access. For example, to filter by the publishedPort in Game Port:

odin fleet servers list --filter="ports['Game Port'].publishedPort = 30097"

This will return servers where the published game port is 30097.

Practical Use Cases#

Filtering for Inactive Servers#

You can quickly filter for servers that are not running:

odin fleet servers list --filter="status.state != 'running'"

This returns all servers whose status.state is not running.

Filtering by Location#

If you need to filter servers based on their location, you can access the location object:

odin fleet servers list --filter="location.country = 'de' AND location.city = 'limburg'"

This will return all servers located in the city of Limburg, Germany.

Advanced Filters#

You can also create more complex filter expressions that combine multiple conditions:

odin fleet servers list --filter="(serverConfig.name = 'Minecraft Production 2' OR serverConfig.name = 'ODIN Fleet') 
AND location.country = 'de'"

This filter will return servers with either the name "Minecraft Production 2" or "ODIN Fleet" that are located in Germany.