You are here: Overviews > Search Requests > File Conditions
dtSearch Text Retrieval Engine Programmer's Reference
File Conditions

File Conditions are used to search by file name, size, or modification date

A file condition consists of the word xfilter and, in parenthesis, a series of one or more filters. Example:

xfilter(name "SMITH.*")

To add a file condition to a search job, use the FileConditions property of a SearchJob (VB, ASP, or Delphi) or the FileConditions member of a DSearchJob (C++) to supply one or more conditions, with "xfilter" and parentheses around the conditions. 

File conditions can be used to limit a search by filename, file date, or size, or to limit a search to documents containing certain words. File conditions do not generate "hits" in search results, which enables dtSearch to process them much more quickly than an equivalent word search. 

The types of supported filters are: 


Filter type
match filename
match filename extension
match file size (can be a range)
match file format
match file modification date (can be a range)
match file creation date (can be a range)
exclude files by name
select documents containing a word pattern
combine a word selection with other selections using OR
combine a word selection with other selections using AND
combine a word selection with other selections using NOT

Except for the name filters, if more than one filter is included all must be satisfied. If more than one name, type, or extension filter is present, the file can match any of the filters. Example:

xfilter(name "abc*.doc" name "abc*.txt" size "1000~~2000" date "01/01/1990~~12/31/1990")

This filter would match any document name starting with abc and ending in .doc or .txt with a size of between 1000 and 2000 bytes that was last modified in 1990. 


For searches by filename extension, it is more efficient to use an ext filter. Multiple ext filters can be combined using the OR operator:

xfilter(ext ".doc") xfilter(ext ".doc") or xfilter(ext ".pdf")


File conditions can be combined with boolean search requests, like this:

(apple or pear) and xfilter(name "abc*.doc")


File conditions can also be combined with other file conditions using boolean operators. If you include multiple file condition expressions in a search request, try to group them into a single boolean expression in the search request, like this:

(apple or pear) and (xfilter(name "abc*.doc") or xfilter(word "abcd*"))


Grouping file conditions this way permits dtSearch to process the search request more efficiently. 


name "filespec"

Matches file if the file name matches the filespec. The filespec must be in quotation marks. Path information is optional. (dtSearch will attempt to match the filespec against filenames with and without path information. A filespec without a slash is matched against the filename without the path.) If the index is created with relative paths, the path information must match the relative path settings for the index. For example, if documents are in c:\docs\text, and the index is in c:\docs\index, the relative path of the documents stored in the index will be ..\text, not c:\docs\text. A search for xfilter(name "..\text\*") or xfilter(name "*text\*") will find documents, but a search for xfilter(name "c:\docs\text\*") will not find any documents, because the index does not store the "c:\docs" part of the path. Stemming, phonic searching, fuzzy searching, and synonym searching cannot be used in a name search (so the characters &, ~, %, and # can be searched in filenames). The * and ? wildcards can be used, and regular expression matching using the ## prefix is also possible.

excl "filespec"

Works like the name filter except that it excludes files by name.

ext ".doc"

Matches the filename extension. The dot is required. A ~ in front of the . negates the expression, matching any file that does not have the extension. Examples:

ext ".doc" (matches file with a .doc extension) ext "~.doc" (matches file without a .doc extension) ext "." (matches file with no extension) size "NNNN~~MMMM"

Matches files with sizes ranging from NNNN to MMMM. The range must be quoted. A ~ in front of the range inverts the meaning (size NOT between NNNN and MMMM). The ~ must be inside the quotation marks.


Matches files with modification dates in the specified range. A specific date, without a range, can also be provided. As with size ranges, a ~ in front of the range negates the meaning. Dates are interpreted as UTC, consistent with the way dtSearch stores file modification dates. Note: dates will be interpreted using the local convention (mm/dd/yy, dd/mm/yy, etc.). To avoid ambiguity, use the following special format: "M01/D31/Y1996". A date can also be expressed relative to the current date using the syntax T+N (for N days after the current date) or T-N (for N days before the current date). T+0 is the current date. Example:

date "T-20~~T+0"
created "MM/DD/YYYY~~MM/DD/YYYY"

Like the date filter except that it applies to the creation date. 

type NN 

type word 

[Applies to indexes created with dtSearch 7.87 and later.] 

The type filter can match a numerical file type id from the TypeId enumeration (for example, 227 for it_PDF). A type filter can also match one of a defined set of type names that match a set of type ids, covering all versions of a product that includes multiple type ids. The defined type names are: text, word, excel, pdf, powerpoint, html, xml, wordperfect, zip, rar, msg, onenote. Additionally, the type name container will match any container, such as RAR, ZIP, or CSV. Examples:

type "word" type 227 type "container"


word "text"

Matches files that contain the specified word. Examples:

word "appl*" word "abc~"

To specify a field for the word, put :: in front of it, like this:

word "type::sedan"

To specify a field with a range, use ~~ just as with dates and sizes, like this:

word "datefield::20020101~~20020131"

Ranges in "word" conditions are always evaluated as text, not as numeric or date values. Therefore, for example, word "id::40~~50" would match an id value of 45, 45000, or 4abc. 

A "word" file condition is useful when you want to select documents that contain a certain word but do not need the word to be highlighted as a hit. A "word" search inside an xfilter expression is different in several ways from including a word in a search request: (1) xfilter searches for a word are often much faster, especially if the text pattern matches many words, in searches of large document collections; (2) only single words can be used (not phrases); (3) words matched are not counted as "hits" in the hit count reported for the document. 

Use orword, andword, and notword to combine multiple word expressions in an xfilter using boolean logic. ("Word" is equivalent to "andword".) Example:

orword "appl*" orword "pear" andword "1234" notword "567"

This request would be evaluated as follows: 

(1) Add documents that contain either appl* or pear 

(2) Exclude documents that do not contain 1234 

(3) Exclude documents that contain 567 

Combining filter expressions this way is more efficient than combining them using boolean connectors, like this:

(xfilter(word "appl*") or xfilter(word "pear")) and xfilter(word "1234") and not xfilter(word "567")
Copyright (c) 1995-2021 dtSearch Corp. All rights reserved.