Filter Condition Syntax (-cond:"FILTER")

Top  Previous  Next

Filter conditions are expressions that can evaluate to true or false.
They are used to filter objects for commands that support the flag -cond:"FILTER", such as ls, setacl, setmeta, put, del.

 
OPERATORS

Operators

Explanation

Example

=

Equal

size = 10 (true if file's size is 10 bytes)

<> , !=

Not equal

year != 2013 (true if file's year is not equal to 2013)
month <> 1 (true if file's month is not equal to 1)

> , >=, <, <=

Greater than, greater than or equal, smaller than, smaller than or equal

sizemb >= 20 AND sizemb <= 30 (true if file's size in MB is between 20 and 30)

+ , - , * , /

Addition, subtraction, multiplication, division

hour + 10 < 20 (true if file's hour plus 10 equal 20)

%

Modulo operation: finds the remainder of division of one number by another

curr_day % 2 = 0 (true on even days)
curr_day % 2 = 1 (true on odd days)
curr_day % 5 = 0 (true every 5 days)

OR , AND

Logical operators. Group parenthesis for precedence.

sizemb > 5 AND (year < 2010 OR year > 2013)

isoneof

True if a value is contained in a list of values. The list of values must be enclosed in { } and each value separated by ; or ,
For text values, * can be used a wildcard to match any text.

day isoneof {1,2,3,4,5,6,7,8} (true if file's day is 1,2,3,4,5,6,7 or 8)
month isoneof {1;3;7;12} (true if file's month is 1,3,7 or 12)
name isoneof {'*.css','*.ini'} (true if file's name matches *.css or *.ini)

isnotoneof

True if a value is NOT contained in a list of values. The list of values must be enclosed in { } and each value separated by ; or ,

day isnotoneof {1,2,3,4,5,6,7,8} (true if day is not 1,2,3,4,5,6,7 or 8)
name isnotoneof {'*.css','*.ini'} (true if file's name does not match *.css or *.ini)

contains

True if a text value contains another text value

name contains 'ab' (true if file's name contains 'ab'. Note that comparison is case insensitive)

starts_with

True if a text value starts with another text value

s3_name starts_with 'A' (true if S3 file's name starts with 'A' or 'a', comparison is case insensitive)

ends_with

True if a text value ends with another text value

s3_name ends_with 'Z' (true if S3 file's name ends with 'Z' or 'z', comparison is case insensitive)

matches

True if a text value matches another text value. Using * matches any text at that location

name matches '*.txt' OR name matches '*.jpg'

regex_matches

True if a text value matches another text value using regular expression syntax.

name regex_matches '^A(.*)|^B(.*)' (true if file's name starts with 'A' or 'B', match is case sensitive, using regular expressions)
name regex_matches '(?i)^A(.*)|^B(.*)' (true if file's name starts with 'A', 'B', 'a' or 'b'. (?i) makes the match case insensitive)

 
LOCAL FILE VARIABLES (ONLY USABLE IN THE CONDITION FOR THE PUT COMMAND)

Local File Variable

Explanation

Example

day

The file's day of the month, in the range 1 through 31

put c:\folder\ mybucket -cond:"day = 15 OR dayofweek = 1" (upload all files in c:\folder\ that were lastly modified on the 15th day of the month or on the first day of the week)

month

The file's month of the year, in the range 1 through 12 (1 = January, 12 = December)

put c:\folder\ mybucket -cond:"month = 1" (upload all files in c:\folder\ that were lastly modified date in January)

year

The file's year, 1970 to 2038

put c:\folder\ mybucket -cond:"year <> 2012" (upload all files in c:\folder\ that were not lastly modified in 2012)

date

The file's date: 'YYYY-MM-DD'

date = '2012-04-03' (true if file's date is '2012-04-03')
date matches '2012-04-*' (true if file's date is in April 2012)
Note that date is a text value and values must be surrounded by two '

time

The file's time: 'HH:MM:SS'

time matches '08:12:10' (true if file's time matches '08:12:10')

hour

The file's hour, in the range 0 through 23

put c:\folder\ mybucket -cond:"hour >= 0 AND hour <= 7" (upload all files in c:\folder\ that were lastly modified between midnight and 7:59 am)

minute

The file's  minute, in the range 0 through 59

put c:\folder\*.jpg mybucket -cond:"minute >= 30" (upload all JPG files in c:\folder\ that were lastly modified in the second half of each hour)

second

The file's second, in the range 0 through 59

put c:\folder\*.jpg mybucket -cond:"second >= 30" (upload all JPG files in c:\folder\ that were lastly modified in the second half of each minute)

dayofweek

The file's day of the week (0 = Sunday, 1 = Monday, etc. to 6 = Saturday)

dayofweek = 0 (true if file's modified timestamp is on a Sunday).
dayofweek = 0 OR dayofweek = 6 (true for Sundays and Saturdays).
dayofweek <> 1 (true if file's day of week is not Monday).

dayofyear

The file's day of the year. Number from 1 to 366

dayofyear = 32 (true if file's modified timestamp is on 1st of February)
dayofyear % 2 = 0 (true file's modified timestamp is on even days)

weeknumber

The file's week number (ISO 8601)

weeknumber = 32 (true if file's timestamp is on the 32nd week of the year)

endofmonth

The file's end of month's date: 'YYYY-MM-DD'

endofmonth = "2012-04-30" (true if file's timestamp is in April 2012)
endofmonth matches "*-*-30" (true if file's timestamp is in a month with 30 days)

age_months

The file's age in months.

put c:\folder\*.jpg mybucket -cond:"age_months > 6" (upload all JPG files in c:\folder\ that were lastly modified more than 6 months ago)

age_days

The file's age in days.

put c:\folder\*.gif mybucket -cond:"age_days < 21" (upload all GIF files in c:\folder\ that were lastly modified less than 21 days ago)

age_hours

The file's age in hours.

age_hours > 1 (true if file is more than 1 hour old)

age_mins

The file's age in minutes.

age_mins <= 30 (true if file is less than 30 minutes old)

age_secs

The file's age in seconds.

age_secs >= 2000  (true if file is more than 2000 seconds old)

name

Local file name

put c:\folder\ mybucket -cond:"name starts_with 'a'" (upload all files in c:\folder\ whose name starts with 'a')

path

Local file path (includes folder)

put c:\folder\ mybucket -cond:"path contains '\subfolder\'" (upload all files in c:\folder\ whose path contains '\subfolder\', e.g. in the subfolder 'subfolder')

extension

Local file extension

put c:\folder\ mybucket -cond:"extension <> '.db'" (upload all files in c:\folder\ with file extension different from '.db')

stem

Local file stem (file name without extension)

put c:\folder\ mybucket -cond:"stem <> 'Read'" (upload all files in c:\folder\ with file stem different from 'read'. Note that <> is case sensitive)

size

File size in bytes

put c:\folder\ mybucket -cond:"size > 20000" (upload all files in c:\folder\ whose size is larger than 20000 bytes)

sizeKB

File size in Kilobytes (KiB)

put c:\folder\ mybucket -cond:"sizeKB > 200" (upload all files in c:\folder\ whose size is larger than 200 Kilobytes)

sizeMB

File size in Megabytes

put c:\folder\ mybucket -cond:"sizeMB < 100" (upload all files in c:\folder\ whose size is smaller than 100 Megabytes)

md5 (or etag)

MD5 of the file (also referred to as 'etag')

put c:\folder\ mybucket -cond:"md5 <> s3_md5" (upload all files in c:\folder\ whose MD5 value , i.e. etag, is different from the MD5 value, i.e. etag, of the corresponding file on S3)

 
S3 OBJECT VARIABLES (USABLE IN ALL FILTER CONDITIONS)

File Time / Date Variables

Explanation

Example

s3_day

The S3 object's day of the month, in the range 1 through 31

ls mybucket\folder\ -cond:"s3_day = 15" (list all files in c:\folder\ that were lastly modified on the 15th day of the month)

s3_month

The S3 object's month of the year, in the range 1 through 12 (1 = January, 12 = December)

del mybucket -s -cond:"s3_month = 1" (recursively delete all files in bucket 'mybucket' that were lastly modified in a January)

s3_year

The S3 object's year, 1970 to 2038

ls mybucket -s -cond:"s3_year <> 2012" (list all files in mybucket that were not lastly modified in 2012)

s3_date

The S3 object's date: 'YYYY-MM-DD'

s3_date = '2012-04-03' (true if S3 file's date is '2012-04-03')
s3_date matches '2012-04-*' (true if S3 file's date is in April 2012)
Note that s3_date is a text value and values must be surrounded by two '

s3_time

The S3 object's time: 'HH:MM:SS'

s3_time matches '08:12:10' (true if file's time matches '08:12:10')

s3_hour

The S3 object's hour, in the range 0 through 23

ls mybucket -s -cond:"s3_hour > 8" (list all files in mybucket that were lastly modified after 8)

s3_minute

The S3 object's  minute, in the range 0 through 59

ls mybucket -s -cond:"s3_minute < 30 " (list all files in mybucket that were lastly modified in the first half of the hour)

s3_second

The S3 object's second, in the range 0 through 59

del mybucket -s -cond:"s3_second % 2 = 0" (recursively delete all files in mybucket that were lastly modified on an even second)

s3_dayofweek

The S3 object's day of the week (0 = Sunday, 1 = Monday, etc. to 6 = Saturday)

del mybucket -s -cond:"s3_dayofweek = 1" (recursively delete all files in bucket 'mybucket' that were lastly modified on a Monday)

s3_dayofyear

The S3 object's day of the year. Number from 1 to 366

ls mybucket -s -cond:"s3_dayofyear = 100" (recursively list all files in bucket 'mybucket' that were lastly modified on the 100th day of a year)

s3_weeknumber

The S3 object's week number (ISO 8601)

ls mybucket -s -cond:"s3_weeknumber = 22" (recursively list all files in bucket 'mybucket' that were lastly modified on the 22nd week of a year)

s3_endofmonth

The S3 object's end of month's date: 'YYYY-MM-DD'

s3_endofmonth = "2012-04-30" (true if S3 file's timestamp is in April 2012)
s3_endofmonth matches "*-*-30" (true if S3 file's timestamp is in a month with 30 days)

s3_age_months

The S3 object's age in months.

ls mybucket\folder\*.txt -cond:"s3_age_months > 6" (list all S3 files with extension txt in mybucket\folder\ that are older than 6 months)

s3_age_days

The S3 object's age in days.

ls mybucket\folder\*.txt -cond:"s3_age_days < 31" (list all S3 files with extension txt in mybucket\folder\ that are newer than 31 days)

s3_age_hours

The S3 object's age in hours.

ls mybucket -cond:"s3_age_hours > 1" (list all S3 files in mybucket that are older than 1 hour)

s3_age_mins

The S3 object's age in minutes.

del mybucket\folder\ -cond:"s3_age_mins < 30" (delete all S3 files in mybucket\folder\ that are newer than 30 minutes)

s3_age_secs

The S3 object's age in seconds.

ls mybucket\folder\*.txt -cond:"s3_age_secs > 90" (list all S3 files with extension txt in mybucket\folder\ that are older than 90 seconds)

s3_name

S3 object's name

ls mybucket\folder\*.txt -cond:"s3_name regex_matches '^A(.*)|^B(.*)'" (list S3 txt files that have file name starting with 'A' or 'B', match is case sensitive, using regular expressions. Use (?i) marker, e.g. (?i)^A(.*)|^B(.*) to make the regular expression case-insensitive)

s3_path

S3 object's path (includes folder)

ls *.htm -s -cond:"s3_path contains '/subfol/'" (list all S3 htm files in all buckets that are in a subfolder called 'subfol')

s3_extension

S3 object's extension

ls -s -cond:"s3_extension = '.htm'" (list all S3 htm files in all buckets)

s3_stem

S3 object's stem (name without extension)

ls -s -cond:"s3_stem = 'check'" (list all S3 files with stem matching check. Stem = file name without extension. Operator = is case sensitive)

s3_size

S3 object's size in bytes

ls mybucket -s -cond:"s3_size>0" (list all S3 files in bucket mybucket that are larger than 0 bytes)
ls mybucket -s -cond:"s3_size=0" (list all empty S3 files in bucket mybucket)

s3_sizeKB

S3 object's size in Kilobytes (KiB)

ls mybucket -s -cond:"s3_sizeKB>1000" (list all S3 files in bucket mybucket that are larger than 1000 Kilobytes)

s3_sizeMB

S3 object's size in Megabytes

ls mybucket -s -cond:"s3_sizeKB>100" (list all S3 files in bucket mybucket that are larger than 100 Megabytes)

s3_md5 (or s3_etag)

S3 object's MD5 (also referred to as 'etag')

put * mybucket -s -cond:"etag <> s3_etag" (upload all files in current folder and subfolders to bucket mybucket if their etag is different from the corresponding S3 etag)

s3_owner

S3 object's owner

del mybucket -s -cond:"s3_owner = 'Marc'" (delete all files in mybucket whose owner is 'Marc')

s3_owner_id

S3 object's owner ID

ls mybucket -s -cond:"s3_owner_id = '1234ABCD'" (list all files in mybucket whose owner ID is ''1234ABCD'')

s3_storage_class

S3 object's storage class

ls mybucket -s -cond:"s3_storage_class = 'STANDARD'" (list all files in mybucket with storage class  'STANDARD')

s3_is_directory

True if S3 object is a directory, false otherwise

ls mybucket -s -cond:"s3_is_directory = true" (list all directories in mybucket)

s3_exists

True if S3 object exists, false otherwise

put * mybucket -s -cond:"s3_exists = false" (upload all files in current folder and subfolders to S3 bucket mybucket only if they do not already exist on S3)

s3_version_id

S3 object's version ID

ls mybucket -s -cond:"s3_version_ID <> '' " (list all objects in mybucket that have a version ID)

s3_is_latest_version

True if an object is the latest version of an object in a versioning enabled bucket

ls mybucket -s -cond:"s3_is_latest_version = true" (list all latest versions of objects in mybucket. This requires mybucket to be versioning enabled)
ls mybucket -s -cond:"s3_is_latest_version = false" (list all previous versions of objects. This requires mybucket to be versioning enabled)
delete mybucket/* -s -cond:"s3_is_latest_version = false" (delete all previous versions of all objects in mybucket. This requires mybucket to be versioning enabled)

s3_prev_version_number

Contains the previous version number, e.g. the last previous version of an object is the number 1, then 2, 3, etc.

del mybucket/* -s -cond:"s3_prev_version_number > 3" (delete previous versions of an object from the fourth version higher. If an object has only 1, 2 or 3 previous versions, then those previous versions are not deleted. This requires mybucket to be versioning enabled)

s3_is_delete_marker

True if object is a delete marker in a versioning enabled bucket

ls mybucket -s -cond:"s3_is_delete_marker = true" (list all delete markers in mybucket. This requires mybucket to be versioning enabled)

cache-control

S3 object's cache-control header

ls mybucket -s -cond:"cache_control = ''" (list all files in mybucket that do not have a cache-control header)

s3_object_max_age

The S3 object's max-age value as specified in the cache-control header

ls mybucket -s -cond:"max-age > 0 " (list all files in mybucket that have max-age in the cache-control header greater than zero)

content-type

S3 object's content-type header

ls mybucket -s -cond:"content-type = 'text/html'" (list all files in mybucket that have the content-type header set to 'text/html')

x-amz-server-side-encryption

S3 object's encryption header

ls mybucket -s -cond:"x-amz-server-side-encryption = 'AES256" (list all files in mybucket that have the x-amz-server-side-encryption header set to 'AES256')

x-amz-website-redirect-location

S3 object's redirect location header

ls mybucket -s -cond:"x-amz-website-redirect-location = '/page2.htm'" (list all files in mybucket that have the  x-amz-website-redirect-location header set to '/page2.htm')

x-amz-version-id

S3 object's version ID header

ls mybucket -s -cond:"x-amz-version-id = 'value'" (list all files in mybucket that have the x-amz-version-id header set to 'value')

x-amz-expiration

S3 object's expiration header

ls mybucket -s -cond:"x-amz-expiration = 'value'" (list all files in mybucket that have the x-amz-expiration header set to 'value')

s3_object_expires

True if S3 objects has an expiration x-amz-expiration header, e.g. it expires

ls mybucket -s -cond:"s3_object_expires = true" (list all files in mybucket that are set to expire at some date in the future)

expiry_date, expiry_year, expiry_month, expiry_day, expiry_dayofweek, expiry_dayofyear, expiry_endofmonth, expiry_weeknumber, expiry_hour, expiry_minute, expiry_second, expiry_time, expiry_timestamp

If a S3 object has an expiry time and date set in the x-amz-expiration header, then these values contain the expiry date (format: YYYY-MM-DD), year (YYYY), month (1 to 12), day (1 to 31), day of week (0 = Sunday, 1 = Monday, etc. to 6 = Saturday), day of year (1 to 366), end of month (YYYY-MM-DD), week number (ISO 8601), hour (0 to 23), minute (0 to 59), second (0 to 59), time (HH:MM:SS) and timestamp (total seconds since epoch)

ls mybucket -s -cond:"expiry_weeknumber = 10" (list all objects in mybucket that will expire in week 10)
ls mybucket -s -cond:"expiry_month = 5 and expiry_year = 2015" (list all objects in mybucket that will expire in May 2015)
ls mybucket -s -cond:"(expiry_month > 5 and expiry_year = 2015) or expiry_year > 2015" (list all objects in mybucket that will expire after May 2015)

expiry_months, expiry_days, expiry_hours, expiry_mins, expiry_secs

If a S3 object has an expiry time and date set in the x-amz-expiration header, then these values contain the number of months, days, hours, minutes and seconds until the object expires

ls mybucket -s -cond:"expiry_months < 10" (list all objects in mybucket that will expire in less than 10 months)
ls mybucket -s -cond:"expiry_days > 100" (list all objects in mybucket that will expire in more  than 100 days)

x-amz-restore

S3 object's restore header

ls mybucket -s -cond:"x-amz-restore = 'value'" (list all objects in mybucket that have the x-amz-restore header set to 'value')

glacier_restored

True if a Glacier object is restored or being restored, e.g. the x-amz-restore header is not empty

ls mybucket -s -cond:"glacier_restored = true" (list all Glacier objects in mybucket that are restored)

restore_ongoing_request

True if a Glacier object is currently being restored to S3 after a restore request

ls mybucket -s -cond:"restore_ongoing_request = true" (list all Glacier objects in mybucket that are currently being restored to S3)

restore_expiry_date, restore_expiry_year, restore_expiry_month, restore_expiry_day, restore_expiry_dayofweek, restore_expiry_dayofyear, restore_expiry_endofmonth, restore_expiry_weeknumber, restore_expiry_hour, restore_expiry_minute, restore_expiry_second, restore_expiry_time, restore_expiry_timestamp

If a restored S3 Glacier object has a restore expiry time and date set in the x-amz-restore header, then these values contain the restore expiry date (format: YYYY-MM-DD), year (YYYY), month (1 to 12), day (1 to 31), day of week (0 = Sunday, 1 = Monday, etc. to 6 = Saturday), day of year (1 to 366), end of month (YYYY-MM-DD), week number (ISO 8601), hour (0 to 23), minute (0 to 59), second (0 to 59), time (HH:MM:SS) and timestamp (total seconds since epoch)

ls mybucket -s -cond:"restore_expiry_month = 12 and expiry_year = 2015" (list all restored Glacier objects in mybucket that will expire in December 2015)
ls mybucket -s -cond:"(restore_expiry_month > 5 and restore_expiry_year = 2015) or restore_expiry_year > 2015" (list all Glacier restored objects in mybucket that will expire after December 2015)

restore_expiry_months, restore_expiry_days, restore_expiry_hours, restore_expiry_mins, restore_expiry_secs

If a restored S3 Glacier object has a restore expiry time and date set in the x-amz-expiration header, then these values contain the number of months, days, hours, minutes and seconds until the object restore expires

ls mybucket -s -cond:"restore_expiry_days < 1" (list all restored Glacier objects in mybucket that will expire in less than 1 day)
ls mybucket -s -cond:"restore_expiry_days > 100" (list all restored Glacier objects in mybucket that will expire in more than 100 days)

x-amz-meta-*

S3 object's custom metadata header

ls mybucket -s -cond:"x-amz-meta-mycustomheader = 'myvalue'" (list all files in mybucket that have the x-amz-meta-mycustomheader header set to ''myvalue'')

s3_acl

S3 object's acl. Different users are separated by |

ls mybucket -s -cond:"s3_acl contains 'marc'" (list all files in mybucket that have an ACL set for 'marc')

s3_acl_is_private

True if S3 object's acl is set to private, false otherwise

ls mybucket -s -cond:"s3_acl_is_private = true" (list all private files in mybucket)

s3_acl_is_public_read

True if S3 object's acl is set to public read, false otherwise

ls mybucket -s -cond:"s3_acl_is_public_read = true" (list all public-read files in mybucket)

s3_acl_is_public_read_write

True if S3 object's acl is set to public read and write, false otherwise

ls mybucket -s -cond:"s3_acl_is_public_read_write = true" (list all public-read-write files in mybucket)

s3_acl_*

S3 object's specific user acl

ls mybucket -s -cond:"s3_acl_marc contains = 'write'" (list all files in mybucket which mark can write)

 

CURRENT TIME VARIABLES (USABLE IN ALL FILTER CONDITIONS)

Time Variables

Explanation

Example

curr_day

The current day of the month, in the range 1 through 31

curr_day = 15 OR curr_dayofweek = 1 (true on Mondays or on the 15th of every month).

curr_month

The current month of the year, in the range 1 through 12 (1 = January, 12 = December)

curr_month = 1 (true in January).

curr_year

The current year, 1970 to 2038

curr_year <> 2012 (true if the current year is not 2012).

curr_date

Today's date: "YYYY-MM-DD"

curr_date = '2013-04-03' (true if date is 2013-04-03)
curr_date matches '2012-04-*' (true in April 2012)

curr_time

Today's time: "HH:MM:SS"

curr_time matches '08:1*:*' (true if the current time is in the first 10 minutes of the 8th hour)

curr_hour

The current hour, in the range 0 through 23

curr_hour >= 0 AND curr_hour <= 7 (true between midnight and 7:59 am).

curr_minute

The current minute, in the range 0 through 59

curr_minute >= 30 (true in the second half of each hour).

curr_second

The current second, in the range 0 through 59

curr_second >= 30 (true in the second half of each minute).

curr_dayofweek

Current day of the week (0 = Sunday, 1 = Monday, etc. to 6 = Saturday)

curr_dayofweek = 0 (true on Sundays).
curr_dayofweek = 0 OR curr_dayofweek = 6 (true on Sundays and Saturdays).
curr_dayofweek <> 1 (true if day of week is not Monday).

curr_dayofyear

Current day of the year. Number from 1 to 366

curr_dayofyear = 32 (true on the 1st of February)
curr_dayofyear % 2 = 0 (true on even days)

curr_weeknumber

Current week number (ISO 8601)

curr_weeknumber = 32 (true on the 32nd week of the year)

curr_endofmonth

Current end of month's date: "YYYY-MM-DD"

curr_endofmonth = '2012-04-30' (true in April 2012)
curr_endofmonth matches '*-*-30' (true if today's month has 30 days)

 

SPECIAL FUNCTIONS (USABLE IN ALL FILTER CONDITIONS)

Function

Explanation

Example

get_env(VariableName)

Returns the text value of the environment variable VariableName

get_env('username') = 'administrator'

to_lower(Text)

Converts Text to lowercase

ls -s -cond:"to_lower(s3_extension) = '.htm'" (list all S3 htm files in all buckets, also if they have extension in uppercase .HTM)

is_lowercase(Text)

Returns true if Text is lower case, false otherwise

ls -s -cond:"is_lowercase(s3_path) = false" (list all objects in all buckets that are not lower case)

pad(Text, Length, Char)

Left pads Text with Char up to Length

pad(s3_month, 2, '0') returns s3_month with 0 padding, i.e. 1 becomes 01, 2 becomes 02, etc, but 12 remains 12.

concat(Text1, Text2)

Concatenates two text strings into one

concat(concat(s3_year, pad(s3_month, 2, '0')), pad(s3_day, 2, '0'))

mid(Text, Start, End)

Returns part of Text between Start and End

mid('Sydney', 3, 2) returns 'dn'
mid('Sydney', 1, 5) returns 'Sydne'
mid('Sydney', 4, 100) returns 'ney'

value(Text)

Returns the numerical value of Text

value(mid('max-age=2000',9,0)) > 1999 returns true
value('2000') returns 2000

extract(Text, Regex)

Extracts part of text from Text using regular expression Regex

extract('Max-age=2000', 'max-age *= *(.*)') returns '2000'

extract_value(Text1, Text2)

Extracts Text2 value from Text1

extract_value('max-age=2000', 'max-age') returns 2000
extract_value('private, max-age=20, no-cache', 'max-age') returns 20