Terminal
Terminal/Skill
Cheatsheet for writing Lucene search queries that filter ImageKit media library files by name, tags, metadata, size, and more.
By ImageKit
Works with
npx skills add imagekit-developer/skills --skill search-assetssearch_media_library searchQueryCall search_media_library on DAM with a tight filter. Do not fetch a broad page and filter in code.
Accounts define arbitrary custom-metadata fields. The user will type normal words ("Nike", "summer campaign", "EMEA", "approved") that may be a field name, a select option, a tag, or only a filename. Never invent "customMetadata.<name>".
For every descriptive word you might put on name or tags:
list_custom_metadata_fields once. Match the word against each field's name, label, and schema.selectOptions (case-insensitive). Use the field's name (not label) as "customMetadata.<name>".list_client_tags with that word as label. If tags come back, filter with tags IN [...] using the returned tag names verbatim.name HAS "…". Literal filenames, extensions, and explicitly "named/called/titled X" go on name without this check.A no-match is cheap: omit that custom-metadata clause rather than guessing a field. Skip filler words ("files", "show me", "assets").
Select types: SingleSelect → = / IN; MultiSelect → IN / NOT IN. Prefer a returned selectOptions value over the user's raw spelling. Text → = : HAS; Number/Date → < <= > >=; Boolean → = with unquoted true/false.
| Input | Use for |
|---|---|
searchQuery | Lucene filter (below). |
path | Folder scope, e.g. /products. |
type | file / file-version / folder / all. Honored only when searchQuery is omitted. |
fileType | image / non-image / all. |
sort | ASC_/DESC_ + CREATED (default ASC_CREATED), UPDATED, NAME, SIZE, WIDTH, HEIGHT, DURATION, RELEVANCE, ORIGINAL_CREATION_DATE. Pair HAS with DESC_RELEVANCE. *_ORIGINAL_CREATION_DATE orders by the reserved _internal_original_created_datetime field; files without a value fall back to upload time. |
limit / skip | Page size (max 1000) and offset. Default page is 20. |
Put a simple folder scope in path and file vs non-image in fileType. Whenever searchQuery is set, put type in searchQuery (type = "folder", or (name HAS "logo") AND type = "folder"). The type argument is ignored in that case and results default to files.
= : < <= > >= IN NOT IN NOT = HAS EXISTS NOT EXISTSAND, OR. Group: ( ... )"double quotes"; numbers and booleans (true/false) unquoted; customMetadata / embeddedMetadata field names must be quoted, e.g. "customMetadata.brand".: = begins-with / within-subfolders. = = exact. HAS = case-insensitive full-text (tokenized).| Field | Operators | Value notes |
|---|---|---|
name | = : IN NOT = NOT IN HAS | = exact (case-sensitive), : begins-with, HAS case-insensitive full-text |
tags | IN NOT IN HAS EXISTS NOT EXISTS | Matches both tags and AITags |
type | = IN NOT = NOT IN | "file" | "file-version" | "folder" |
id | = IN NOT = NOT IN | fileId or folderId |
createdAt / updatedAt | = < <= > >= IN NOT = NOT IN | ISO 8601 or relative ("1h" "2d" "3w" "4m" "1y") |
width / height | = < <= > >= IN NOT = NOT IN | Pixels; images only |
size | = < <= > >= IN NOT = NOT IN | Bytes (1024) or "1mb" / "10kb" |
videoDuration | = < <= > >= IN NOT = NOT IN | Videos only. Quoted with unit: "30sec" "1.5min" "2hr" (or s/m/h); a bare number is seconds |
format | = IN | "jpg" "png" "webp" "gif" "svg" "avif" "pdf" "mp4" … |
private / published / transparency | = | Boolean, unquoted |
createdBy | = IN NOT = NOT IN | Uploader email |
path | = : IN NOT = NOT IN | = exact folder; : folder + subfolders |
"customMetadata.<field>" | type-dependent | Quote the field name. Discover via list_custom_metadata_fields. The reserved _internal_original_created_datetime (Date, label "Original creation date") is listed with reserved: true only on accounts that enabled it |
"embeddedMetadata.<field>" | type-dependent | From the file, not the DAM schema. Keywords uses IN/EXISTS; DateTimeOriginal uses date ops; LocationTaken supports geo ("40,100 5km") |
name HAS "red dress"
name = "red-dress.jpg"
name : "red-dress"
createdAt > "7d" AND size > "2mb"
tags IN ["sale", "summer"]
tags NOT EXISTS
format IN ["jpg", "webp"]
path : "/sales-banner/"
"customMetadata.brand" = "nike"
"customMetadata.Region" IN ["EMEA"]
"customMetadata.rating" > 4.3
"embeddedMetadata.DateTimeOriginal" > "1y"
videoDuration > "1min" AND format = "mp4"
"customMetadata._internal_original_created_datetime" < "2021-01-01"
(size < "1mb" AND width > 500) OR (tags IN ["summer-sale", "banner"])
User says "Nike assets" → list_custom_metadata_fields finds brand / options including Nike → "customMetadata.brand" = "Nike". Do not search name HAS "Nike" if a field or tag matched.
name = / : are case-sensitive; use HAS for case-insensitive matching.tags queries search both tags and AITags.HAS tokenizes on spaces/punctuation; the last token matches as a prefix. Pair with sort: DESC_RELEVANCE.private, published, transparency) are unquoted; string values are quoted.width / height / transparency apply to images only; videoDuration applies to videos only. Units are sec / min / hr, not minutes / hours.ASC_ORIGINAL_CREATION_DATE / DESC_ORIGINAL_CREATION_DATE only when list_custom_metadata_fields returns _internal_original_created_datetime; otherwise use *_CREATED."customMetadata.<field>" only matches fields defined on the account. Quote the whole token.type tool argument is ignored whenever searchQuery is set. Put type = "folder" (or type IN [...]) in searchQuery instead.