{ids:slices:conds:sort:delimiter:restrict_ids:limit}

Description

Returns the long ids of items from one or more slices, filtered by conditions and ordered, as a delimiter-joined list. It is the building block for data-reading templates: feed its output to item, view, count or unique to display or tally matching content without writing SQL. Only active items are searched (holding, pending and trashed items are skipped), and ids are returned as 32-character long ids joined by the delimiter (default a dash). With no match the result is an empty string; with delimiter set to json the ids come back as a JSON array. The conds parameter is a d- string of field-operator-value triplets (operators include = and == for exact match, the comparisons less-than greater-than and not-equal, CONTAIN and BEGIN for text, ISNULL and NOTNULL for empty checks). sort takes one or more field ids, ascending by default or descending with a trailing dash. restrict_ids intersects the search with a known id set, and limit caps the count (a negative limit returns the last N).

Parameters

slices required

Dash-separated list of slice ids to search. At least one slice is normally given; items from all listed slices are merged into one result set before sorting. Without a slice (and without restrict_ids) nothing is returned.

Allowed values One or more valid 32-character hex slice IDs, dash-separated. Example: d8d0377d443a1d4b30a4fe234a66f1e7 or d8d0377d443a1d4b30a4fe234a66f1e7-15deb349ab0e1a90329f1635b9502be6
conds optional

Filter conditions in d- form: d- followed by repeating field-operator-value triplets, joined by dashes, e.g. d-headline........-==-Gamma or d-integer.........->-50. Operators include = and == (exact), the comparisons (< > <> <= >=), CONTAIN and BEGIN (text), ISNULL and NOTNULL (empty checks), BITSET and REGEXP. Multiple triplets are AND-combined. Build conditions from variables with the conds expression. Empty means no filter (all items).

Allowed values Condition string in AA filter format. Example: d-category.......-=-news (category equals "news"). Operators: = (equals), != (not equal), -= (contains), =- (begins with), < (less than), > (greater than). Field IDs are padded to 16 characters with dots.
sort optional

One or more field ids to order the result by. Ascending by default; add a trailing dash for descending, e.g. publish_date....- for newest first. Separate several sort keys with commas. Empty leaves the default order.

Allowed values Sort field ID string (16 characters, dot-padded) optionally prefixed with dash for descending. Examples: publish_date.....- (ascending), -publish_date.....- (descending), -headline........- (by title descending).
delimiter optional default -

Separator placed between the returned ids. Defaults to a dash, which is what item, view, count and unique expect as their id separator. The special value json returns the ids as a JSON array instead.

Allowed values Any string. Default: - (dash). Common alternatives: , (comma) or | (pipe) depending on the downstream consumer.
restrict_ids optional

Dash-separated id set that pre-limits the search: the result is the intersection of these ids with the conds filter and the listed slices. Useful to narrow a large slice to a known subset. Empty searches all items.

Allowed values Dash-separated list of item IDs (short 16-char or long 32-char hex). Example: abc123-def456. Leave empty to skip pre-filtering.
limit optional default 0 (no limit)

Maximum number of ids to return, applied after filtering and sorting. A negative limit returns the last N ids instead of the first N. Empty or 0 returns all matches.

Allowed values Positive integer. Default: empty (no limit). Example: 5 returns at most 5 IDs.

Examples

test{count:{ids:9e1d2b9f88e3d6c3bf0eb967378610d6}}
Expected10
Actual10
With only a slice id, {ids:} returns the long ids of every active item in that slice. Here the Stable test slice holds 10 active items; wrapping in {count:} gives the tally without re-reading the database.
test{count:{ids:9e1d2b9f88e3d6c3bf0eb967378610d6:d-integer.........->-50}}
Expected4
Actual4
The conds parameter starts with d- then repeats field-operator-value triplets. Here it keeps items whose integer field is greater than 50 (the Stable rows 99, 100, 255, 1000), so four items match.
test{item:{ids:9e1d2b9f88e3d6c3bf0eb967378610d6:d-headline........-==-Gamma}:_#NUMBER__}
Expected100
Actual100
Operator == is an exact, non-SQL match. {ids:} returns the id of the one row whose headline equals Gamma; {item:} then prints that item's integer field through its alias _#NUMBER__ (which is 100). Inside {item:ID:CONTENT} you must read target fields by their _# alias, not by a field-getter.
test{item:{ids:9e1d2b9f88e3d6c3bf0eb967378610d6:d-integer.........->-40:integer.........}:_#HEADLINE: }
ExpectedBeta Eta Gamma Theta Kappa
ActualBeta Eta Gamma Theta Kappa
The third parameter sorts the matched ids. integer......... sorts ascending; append a trailing dash to sort descending. Here items with integer over 40 come back ordered 42, 99, 100, 255, 1000, so their headlines print in that order joined by a space.
test{item:{ids:9e1d2b9f88e3d6c3bf0eb967378610d6::integer.........:::3}:_#NUMBER__:,}
Expected0,0,1
Actual0,0,1
The sixth parameter caps the result. With empty conds and sort by integer ascending, limit 3 keeps the three smallest values (0, 0, 1). A negative limit returns the last N instead. Note the empty colons that skip the unused conds, delimiter and restrict_ids parameters to reach limit.
test{count:{ids:9e1d2b9f88e3d6c3bf0eb967378610d6:d-integer.........->-50:::5726c2c6b035d7aab450d1794e9e90d7-4f3362a62847fe1f8c59ba28a92d42c0}}
Expected1
Actual1
The fifth parameter pre-limits the search to a dash-separated id set, intersected with the conds. The two ids passed are Gamma (integer 100) and Beta (integer 42); only Gamma also satisfies integer over 50, so one item matches.
test{ids:9e1d2b9f88e3d6c3bf0eb967378610d6:d-headline........-==-Gamma:headline........:json}
Expected["5726c2c6b035d7aab450d1794e9e90d7"]
Actual["5726c2c6b035d7aab450d1794e9e90d7"]
The fourth parameter sets the separator between ids (default is a dash). The special value json returns the ids as a JSON array instead, handy when another tool or {foreach:...:json} consumes the result. Here the single matching id (Gamma) is wrapped as a one-element array.
test[{ids:9e1d2b9f88e3d6c3bf0eb967378610d6:d-headline........-==-Nonexistent}]
Expected[]
Actual[]
When nothing matches, {ids:} returns an empty string (shown here inside square brackets so the empty result is visible). {ids:} also searches active items only - holding, pending and trashed items are never returned.
v2003 Deprecated: no Alternative: -
← All expressions