DocumentationRecipesReferenceGraphQLChangelog
Log In
Documentation

Filtering assets from cloud storage

This feature enables direct asset filtering of objects in your connected cloud storage bucket. By applying filters, you can cherrypick assets to sync with the project.

Prefix Filter

The prefix filter allows specifying a single parent folder path for all assets to synced with project. All folders and assets within the specified prefix are selected.

The specified path must be complete and end with a /. Wildcard (*) support isn't available in this field. Additionally, the parent folder doesn't need to be at the top level of the bucket; it can be nested within other folders.

For example, if the filter is set to folder1/, the following bucket structure will only retrieve the assets folder1/subfolder1/asset1.jpeg, folder1/subfolder1/asset2.jpeg, folder1/subfolder2/asset1.jpeg, folder1/subfolder2/asset2.jpeg:

folder1
  \\
    subfolder1
       \\
        asset1.jpeg
        asset2.jpeg
    subfolder2
       \\
        asset1.jpeg
        asset2.jpeg
folder2
  \\
    subfolder1
       \\
        asset1.jpeg
        asset2.jpeg
    subfolder2
       \\
        asset3.jpeg

While with folder1/subfolder1/, the bucket structure will only retrieve the assets folder1/subfolder1/asset1.jpeg and folder1/subfolder1/asset2.jpeg,

When no prefix is specified, all assets will be submitted to the include and exclude filters.

Include and exclude filters

The include and exclude filters allow to refine the selection of assets retrieved from a bucket based on their paths. These filters are applied after the prefix filter, allowing them to selectively include or exclude assets from the subset of assets already identified by the prefix.

Syntax

The include and exclude filters accept one or more path patterns separated by commas. Each path pattern can be a complete folder path or a wildcard expression using an asterisk (*) to match multiple characters. You can combine paths patterns within a single filter.

Supported patterns :

  1. Simple string: Matches all paths starting with the specified string, or complete paths. This is similar to a prefix pattern but doesn't require a complete folder name or a trailing slash. You can also provide a complete path as the string. For example, in the following bucket, the pattern vehicles/blue-* matches vehicles/blue-car.jpg and vehicles/blue-plane.jpg, while vehicles/blue-car.jpg will only match the selected path:
vehicles
      \\
      blue-car.jpg
      green-car.jpg
      blue-plane.jpg
      green-plane.jpg

  1. Wildcard at the beginning of the pattern: An asterisk preceding a string will match all paths ending with the piece of string after the wildcard. For example, in the following bucket, the pattern *.jpeg matches vehicles/blue-car.jpeg and vehicles/blue-plane.jpeg:
vehicles
      \\
      blue-car.jpeg
      blue-car.png
      blue-plane.jpeg
      blue-plane.png

  1. In-path wildcards: A string with one or more wildcards will match all the paths that start with the initial string before the wildcard, end with the last piece of string, and include the strings inbetween the wildcards (if more than one). For example, in the following bucket, the pattern heavy*blue*jpg matches heavy-vehicles/blue-truck.jpg and heavy-animals/blue-whale.jpg:
heavy-vehicles
      \\
      blue-plane.png
      blue-truck.jpg

heavy-animals
      \\
      blue-whale.png
      blue-whale.jpg

  1. Trailing wildcard: Matches all the paths that start with the pattern before the trailing wildcard (e.g., heavy*). For example, the pattern heavy*blue* will match heavy-vehicles/blue-truck.jpg and heavy-animals/blue-whale.png.
heavy-vehicles
     \\
     green-train.png
     blue-truck.jpg

heavy-animals
     \\
     blue-whale.png
     grey-elephant.jpg

  1. Initial and trailing wildcards: Matches all paths that include all of the strings between the wildcards. You can add multiple wildcards between the initial and trailing ones. For example, the pattern heavy* will match heavy-vehicles/blue-truck.jpg and animals/heavy-whale.jpg, and food/butter.heavy, while g*e* wil match animals/grey-elephant.jpg and languages/italian.it.:
heavy-vehicles
      \\
      blue-truck.jpg
animals
      \\
      heavy-whale.png
      grey-elephant.jpg
food
      \\
      butter.heavy
      tomato.light
languages
      \\
      italian.it

Application order

The include and exclude filters operate in a sequential manner, with the include filter applied first. This means that the exclude filter only modifies the subset of assets that are already included by the include filter.

Cases:

The combination of the include and exclude filters enables precise control over the retrieved assets. There are three main cases to consider:

  1. No include or exclude provided: All assets matching the prefix filter will be retrieved.
  2. Only include paths provided: Only assets that match the specified path patterns will be included in the retrieved set. For example, in the following bucket, include set to heavy-vehicles/blue-, heavy-animals/grey- will retrieve heavy-vehicles/blue-truck.jpg, heavy-vehicles/blue-plane.jpg, and heavy-animals/grey-elephant.jpg:
heavy-vehicles
      \\
      blue-plane.jpg
      green-plane.png
      blue-truck.jpg

heavy-animals
      \\
      blue-whale.png
      grey-elephant.jpg

  1. Only exclude paths provided: Assets matching the specified path patterns will be removed from the subset of assets already included by the prefix filter. For example, in the following bucket, exclude set to .png will retrieve only heavy-vehicles/blue-truck.jpg and heavy-animals/grey-elephant.jpg:
heavy-vehicles
      \\
      green-plane.png
      blue-truck.jpg

heavy-animals
      \\
      blue-whale.png
      grey-elephant.jpg

  1. Both include and exclude patterns provided: The algorithm first applies the include filter, retaining only the assets that match the specified path patterns. Then, it applies the exclude filter, removing any assets that match the excluded patterns. The final result is the intersection of the included and excluded assets. For example, in the following bucket, include set to blue* exclude set to .png will retrieve only heavy-vehicles/blue-truck.jpg:
heavy-vehicles
      \\
      green-plane.png
      blue-truck.jpg

heavy-animals
      \\
      blue-whale.png
      grey-elephant.jpg

Please keep in mind that the include and exclude filters will only be applied to the folders and objects selected by the prefix filter. You don't need to include the prefixed folders in the include and exclude filters, as they will be searched directly within the prefixed folder. For instance, in the following bucket, setting the prefix to heavy-vehicles/ and the include filter to blue will retrieve heavy-vehicles/blue-truck.jpg and heavy-vehicles/blue-car.jpg, while setting the prefix to heavy-vehicles/ and the include filter to heavy-vehicles/blue will yield no results because there is no nested heavy-vehicles/ folder within heavy-vehicles/:

heavy-vehicles
  \\
  green-plane.png
  blue-truck.jpg
  blue-car.jpg

heavy-animals
  \\
  blue-whale.png
  grey-elephant.jpg