| 1 | <h2 id="about">About Search Syntax</h2> |
| 2 | <p> |
| 3 | The search engine allows users to locate uploads via tags that are associated with an upload and some other metadata such as uploader and user count. It also permits chaining together specified tags and metadata to search for specific logical combinations, |
| 4 | to allow more precise filtering. This guide explains the syntax and features of individual terms and then shows how they are combined into more complex queries. |
| 5 | </p> |
| 6 | <ol> |
| 7 | <li><a href="#about">About Search Syntax</a> |
| 8 | </li> |
| 9 | <li> |
| 10 | <a href="#terms">Search Terms</a> |
| 11 | <ol> |
| 12 | <li><a href="#tag-behavior">Tag Search Behavior</a> |
| 13 | </li> |
| 14 | <li><a href="#fields">Searching Through Other Fields</a> |
| 15 | </li> |
| 16 | <li><a href="#numeric-range">Numeric Range Queries</a> |
| 17 | </li> |
| 18 | <li><a href="#date-range">Date/Time Range Queries</a> |
| 19 | </li> |
| 20 | <li><a href="#supported-fields">Supported Fields</a> |
| 21 | </li> |
| 22 | </ol> |
| 23 | </li> |
| 24 | <li> |
| 25 | <a href="#special-characters">Special Characters and Suffixes</a> |
| 26 | <ol> |
| 27 | <li><a href="#wildcards">Wildcards</a> |
| 28 | </li> |
| 29 | <li><a href="#escaping">Escaping Special Characters</a> |
| 30 | </li> |
| 31 | <li><a href="#fuzzy">Approximate (Fuzzy) String Matching</a> |
| 32 | </li> |
| 33 | </ol> |
| 34 | </li> |
| 35 | <li> |
| 36 | <a href="#grammar">Search Grammar: Term Operators and Combinations</a> |
| 37 | <ol> |
| 38 | <li><a href="#expressions">Expressions</a> |
| 39 | </li> |
| 40 | <li><a href="#expressions-summary">Summary Table</a> |
| 41 | </li> |
| 42 | <li><a href="#negation">Negation</a> |
| 43 | </li> |
| 44 | <li><a href="#and-expressions">Commas and AND Expressions</a> |
| 45 | </li> |
| 46 | <li><a href="#or-expressions">OR Expressions</a> |
| 47 | </li> |
| 48 | <li> |
| 49 | <a href="#compound">Compound Expressions</a> |
| 50 | <ol> |
| 51 | <li><a href="#precedence">Operator Precedence</a> |
| 52 | </li> |
| 53 | <li><a href="#parentheses">Defining Subexpressions with Parentheses</a> |
| 54 | </li> |
| 55 | <li><a href="#auto-escaping">Automatic Parentheses Escaping</a> |
| 56 | </li> |
| 57 | </ol> |
| 58 | </li> |
| 59 | </ol> |
| 60 | </li> |
| 61 | <li><a href="#boosting">Boosting Terms</a> |
| 62 | </li> |
| 63 | </ol> |
| 64 | <h2 id="terms">Search Terms</h2> |
| 65 | <p> |
| 66 | Specific searches require the inclusion of search terms, which individually define the criteria expected of each upload result to be returned by the search engine. |
| 67 | </p> |
| 68 | <h3 id="tag-behavior">Tag Search Behavior</h3> |
| 69 | <p> |
| 70 | Searching a single term is obvious: merely type in the term you want. By default, the term you use will be searched among the indexed image tags and aliases. Thus, a search for |
| 71 | <code><a href="/search?q=canine">canine</a></code> would, as you may surmise, result in all appropriately tagged and indexed pictures of canine tagged images. Aliases are also indexed, so a search for the tag alias <code><a href="/search?q=smile">smile</a></code> is the same as one for |
| 72 | <code><a href="/search?q=smiling">smiling</a></code>. |
| 73 | </p> |
| 74 | <p> |
| 75 | The default tag search has particular aspects associated with it for your convenience. For tag searches, case is insensitive. This means capitalization is irrelevant for queries. For example, the search queries |
| 76 | <code><a href="/search?q=Canine">Canine</a> |
| 77 | </code> and |
| 78 | <code><a href="/search?q=canine">canine</a> |
| 79 | </code> will share the same result set. |
| 80 | </p> |
| 81 | <h3 id="fields">Searching Through Other Fields</h3> |
| 82 | <p> |
| 83 | Other fields are also indexed, and you can search them using the namespace convention that is also used by tags. Namely, one enters the field name followed by a colon, and finally, the target value. For example, to search for images with a width of 1920, |
| 84 | we would search within the |
| 85 | <code>width</code> field and so construct the query |
| 86 | <code><a href="/search?q=width%2a1920">width:1920</a></code>. If a tag with namespace were to share the namespace with a given field, it can still be queried via quoting or escaping. |
| 87 | </p> |
| 88 | <h3 id="numeric-range">Numeric Range Queries</h3> |
| 89 | <p> |
| 90 | Numeric fields in particular support queries for ranges of possible values. A qualifier can be added to the end of the field name with a single period to indicate desired results that are greater than or less than the supplied value; the value can be |
| 91 | optionally included, too. To find images with a score greater than 100, we would enter |
| 92 | <code><a href="/search?q=score.gt%2a100">score.gt:100</a></code>. For an inclusive search of scores greater than |
| 93 | <em>or equal to</em> 100, we would instead enter |
| 94 | <code><a href="/search?q=score.gt%2a100">score.gte:100</a></code>. The following table enumerates the supported qualifiers. |
| 95 | </p> |
| 96 | <table class="table"> |
| 97 | <thead> |
| 98 | <tr> |
| 99 | <th>Qualifier</th> |
| 100 | <th>Meaning</th> |
| 101 | <th>Example</th> |
| 102 | </tr> |
| 103 | </thead> |
| 104 | <tbody> |
| 105 | <tr> |
| 106 | <td> |
| 107 | <code>gt</code> |
| 108 | </td> |
| 109 | <td> |
| 110 | Values greater than specified, and not including the specified value |
| 111 | </td> |
| 112 | <td> |
| 113 | <code><a href="/search?q=score.gt%3a100">score.gt:100</a> |
| 114 | </code></td> |
| 115 | </tr> |
| 116 | <tr> |
| 117 | <td> |
| 118 | <code>gte</code> |
| 119 | </td> |
| 120 | <td> |
| 121 | Values greater than or equal to specified |
| 122 | </td> |
| 123 | <td> |
| 124 | <code><a href="/search?q=score.gte%3a100">score.gte:100</a> |
| 125 | </code></td> |
| 126 | </tr> |
| 127 | <tr> |
| 128 | <td> |
| 129 | <code>lt</code> |
| 130 | </td> |
| 131 | <td> |
| 132 | Values less than specified, and not including the specified value |
| 133 | </td> |
| 134 | <td> |
| 135 | <code><a href="/search?q=width.lt%3a100">width.lt:100</a> |
| 136 | </code></td> |
| 137 | </tr> |
| 138 | <tr> |
| 139 | <td> |
| 140 | <code>lte</code> |
| 141 | </td> |
| 142 | <td> |
| 143 | Values less than or equal to specified |
| 144 | </td> |
| 145 | <td> |
| 146 | <code><a href="/search?q=width.lte%3a100">width.lte:100</a> |
| 147 | </code></td> |
| 148 | </tr> |
| 149 | </tbody> |
| 150 | </table> |
| 151 | <h3 id="date-range">Date/Time Range Queries</h3> |
| 152 | <p> |
| 153 | Date and time values are specified using a tweaked subset of the |
| 154 | <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601 standard</a>. A full date is specified by four-digit year, followed by two-digt month and date, with each value delimited by a hyphen, i.e., "YYYY-mm-DD". Like in ISO 8601, one can specify just |
| 155 | the month or even just the year, as long as the less precise information is included in left-to-right order without dangling hyphens. This is semantically interpreted as the range of the entire period (not just the first day of the month, etc.). For |
| 156 | example, |
| 157 | <code>2020-05</code> represents the entire month of May 2020. |
| 158 | </p> |
| 159 | <p> |
| 160 | Given a full date, a specification for the time of day can be added. To do so, separate the time with a |
| 161 | <code>T</code> or space, followed by the hours, minutes, and seconds, each specified ' with two digits and separated by a colon, i.e., "HH:MM:SS". The hours follow a 24-hour clock. As with date values, one may alternatively specify entire minutes and |
| 162 | even hours by truncating the value without a dangling colons. The value |
| 163 | <code>2020-05-20 16</code> represents the entire hour of 4 PM on 20 May 2020 (UTC). The entire first minute can be specified with |
| 164 | <code>2020-05-20 16:00</code>. |
| 165 | </p> |
| 166 | <p> |
| 167 | By default, time follows international UTC ("Zulu") time. (In terms of the ISO 8601 standard, a |
| 168 | <code>Z</code> suffix is implied.) One may specify an offset for local time by affixing a plus or minus sign, followed by the offset hours as two digits, a colon, and the offset minutes (usually |
| 169 | <code>00</code>), e.g., |
| 170 | <code>-04:00</code> for US Eastern Daylight Time (EDT). Note that unlike ISO 8601, this can be attached to dates as well as times, to ensure date boundaries fit the locale of interest. For example, |
| 171 | <code>2020-05:00</code> represents the year of 2020 with an offset of minus five hours (US Eastern Standard Time). |
| 172 | </p> |
| 173 | <p> |
| 174 | Date/time range queries also accept range qualifiers. The |
| 175 | <code>gt</code> and |
| 176 | <code>lt</code> qualifiers omit everything matching the implied time range of the specified value, whereas |
| 177 | <code>gte</code> and |
| 178 | <code>lte</code> include the entirety of said time range. |
| 179 | </p> |
| 180 | <p> |
| 181 | The following examples are valid search queries. |
| 182 | </p> |
| 183 | <table class="table"> |
| 184 | <thead> |
| 185 | <tr> |
| 186 | <th>Example</th> |
| 187 | <th>Explanation</th> |
| 188 | </tr> |
| 189 | </thead> |
| 190 | <tbody> |
| 191 | <tr> |
| 192 | <td> |
| 193 | <code><a href="/search?q=created_at%3a2020">created_at:2020</a> |
| 194 | </code></td> |
| 195 | <td>Returns all uploads made in 2020 (UTC).</td> |
| 196 | </tr> |
| 197 | <tr> |
| 198 | <td> |
| 199 | <code><a href="/search?q=created_at%3a2020%2b08:00">created_at:2020+08:00</a> |
| 200 | </code></td> |
| 201 | <td>Returns all uploads made in 2020 (SGT).</td> |
| 202 | </tr> |
| 203 | <tr> |
| 204 | <td> |
| 205 | <code><a href="/search?q=created_at%3a2020-05">created_at:2020-05</a> |
| 206 | </code></td> |
| 207 | <td>Returns all uploads made in May 2020 (UTC).</td> |
| 208 | </tr> |
| 209 | <tr> |
| 210 | <td> |
| 211 | <code><a href="/search?q=created_at%3a2020-05-03%3a00">created_at:2020-05-03:00</a> |
| 212 | </code></td> |
| 213 | <td>Returns all uploads made in May 2020 (BRT).</td> |
| 214 | </tr> |
| 215 | <tr> |
| 216 | <td> |
| 217 | <code><a href="/search?q=created_at%3a2020-05-01">created_at:2020-05-01</a> |
| 218 | </code></td> |
| 219 | <td>Returns all uploads made in 1 May 2020 (UTC).</td> |
| 220 | </tr> |
| 221 | <tr> |
| 222 | <td> |
| 223 | <code><a href="/search?q=created_at%3a2020-05-01%2b08%3a00">created_at:2020-05-01+08:00</a> |
| 224 | </code></td> |
| 225 | <td>Returns all uploads made in 1 May 2020 (SGT).</td> |
| 226 | </tr> |
| 227 | <tr> |
| 228 | <td> |
| 229 | <code><a href="/search?q=created_at%3a2020-05-01+01">created_at:2020-05-01 01</a> |
| 230 | </code></td> |
| 231 | <td>Returns all uploads made in the hour of 1 AM of 1 May 2020 (UTC).</td> |
| 232 | </tr> |
| 233 | <tr> |
| 234 | <td> |
| 235 | <code><a href="/search?q=created_at%3a2020-05-01+01Z">created_at:2020-05-01 01Z</a> |
| 236 | </code></td> |
| 237 | <td> |
| 238 | Returns all uploads made in the hour of 1 AM on 1 May 2020 (UTC). The zero UTC offset designator ("Zulu") is explicit. |
| 239 | </td> |
| 240 | </tr> |
| 241 | <tr> |
| 242 | <td> |
| 243 | <code><a href="/search?q=created_at%3a2020-05-01T01Z">created_at:2020-05-01T01Z</a> |
| 244 | </code></td> |
| 245 | <td> |
| 246 | Returns all uploads made in the hour of 1 AM on 1 May 2020 (UTC). This uses the standard "T" separator associated with ISO 8601. |
| 247 | </td> |
| 248 | </tr> |
| 249 | <tr> |
| 250 | <td> |
| 251 | <code><a href="/search?q=created_at%3a2020-05-01+01-05%3a00">created_at:2020-05-01 01-05:00</a> |
| 252 | </code></td> |
| 253 | <td>Returns all uploads made in the hour of 1 AM on 1 May 2020 (EDS).</td> |
| 254 | </tr> |
| 255 | <tr> |
| 256 | <td> |
| 257 | <code><a href="/search?q=created_at%3a2020-05-01+01%3a00">created_at:2020-05-01 01:00</a> |
| 258 | </code></td> |
| 259 | <td>Returns all uploads made sometime in the minute of 1:00 AM on 1 May 2020 (UTC).</td> |
| 260 | </tr> |
| 261 | <tr> |
| 262 | <td> |
| 263 | <code><a href="/search?q=created_at%3a2020-05-01+01%3a00Z">created_at:2020-05-01 01:00Z</a> |
| 264 | </code></td> |
| 265 | <td> |
| 266 | Returns all uploads made sometime in the minute of 1:00 AM on 1 May 2020 (UTC). The zero UTC offset designator ("Zulu") is explicit. |
| 267 | </td> |
| 268 | </tr> |
| 269 | <tr> |
| 270 | <td> |
| 271 | <code><a href="/search?q=created_at%3a2020-05-01+00%3a00%3a00">created_at:2020-05-01 00:00:00</a> |
| 272 | </code> |
| 273 | <td>Returns all uploads made exactly at midnight on 1 May 2020 (UTC).</td> |
| 274 | </td> |
| 275 | </tr> |
| 276 | <tr> |
| 277 | <td> |
| 278 | <code><a href="/search?q=created_at%3a2020-05-01+00%3a00%3a00%2b08%3a00">created_at:2020-05-01 00:00:00+08:00</a> |
| 279 | </code></td> |
| 280 | <td>Returns all uploads made exactly at midnight on 1 May 2020 (SGT).</td> |
| 281 | </tr> |
| 282 | <tr> |
| 283 | <td> |
| 284 | <code><a href="/search?q=created_at.lt%3a2020">created_at.lt:2020</a> |
| 285 | </code></td> |
| 286 | <td>Returns all uploads before the start of 2020 (UTC).</td> |
| 287 | </tr> |
| 288 | <tr> |
| 289 | <td> |
| 290 | <code><a href="/search?q=created_at.gte%3a2020-05-04">created_at.gte:2020-05-04</a> |
| 291 | </code></td> |
| 292 | <td>Returns all uploads since and including the entire day of 4 May 2020.</td> |
| 293 | </tr> |
| 294 | </tbody> |
| 295 | </table> |
| 296 | <h3 id="supported-fields">Supported Fields</h3> |
| 297 | <p> |
| 298 | The following table enumerates all of the supported fields, with examples. |
| 299 | </p> |
| 300 | <table class="table"> |
| 301 | <thead> |
| 302 | <tr> |
| 303 | <th>Field Selector</th> |
| 304 | <th>Type</th> |
| 305 | <th>Description</th> |
| 306 | <th>Example</th> |
| 307 | </tr> |
| 308 | </thead> |
| 309 | <tbody> |
| 310 | <tr> |
| 311 | <td> |
| 312 | <code>aspect_ratio</code> |
| 313 | </td> |
| 314 | <td>Numeric Range</td> |
| 315 | <td>Matches any image with the specified aspect ratio.</td> |
| 316 | <td> |
| 317 | <code><a href="/search?q=aspect_ratio%3a1">aspect_ratio:1</a> |
| 318 | </code></td> |
| 319 | </tr> |
| 320 | <tr> |
| 321 | <td> |
| 322 | <code>comment_count</code> |
| 323 | </td> |
| 324 | <td>Numeric Range</td> |
| 325 | <td>Matches any image with the specified number of comments</td> |
| 326 | <td> |
| 327 | <code><a href="/search?q=comment_count.gt%3a50">comment_count.gt:50</a> |
| 328 | </code></td> |
| 329 | </tr> |
| 330 | <tr> |
| 331 | <td> |
| 332 | <code>created_at</code> |
| 333 | </td> |
| 334 | <td>Date/Time Range</td> |
| 335 | <td>Matches any image posted at the specified date and/or time.</td> |
| 336 | <td> |
| 337 | <code><a href="/search?q=created_at%3a2020-04-01">created_at:2020-04-01</a> |
| 338 | </code></td> |
| 339 | </tr> |
| 340 | <tr> |
| 341 | <td> |
| 342 | <code>description</code> |
| 343 | </td> |
| 344 | <td>Full Text</td> |
| 345 | <td> |
| 346 | Full-text search against image descriptions with the specified string. |
| 347 | </td> |
| 348 | <td> |
| 349 | <code><a href="/search?q=description%3aderp">description:derp</a> |
| 350 | </code></td> |
| 351 | </tr> |
| 352 | <tr> |
| 353 | <td> |
| 354 | <code>downvotes</code> |
| 355 | </td> |
| 356 | <td>Numeric Range</td> |
| 357 | <td>Matches any image with the specified downvote count.</td> |
| 358 | <td> |
| 359 | <code><a href="/search?q=downvotes%3a0">downvotes:0</a> |
| 360 | </code></td> |
| 361 | </tr> |
| 362 | <tr> |
| 363 | <td> |
| 364 | <code>faved_by</code> |
| 365 | </td> |
| 366 | <td>Literal</td> |
| 367 | <td>Matches any image favorited by the specified user. Case-insensitive.</td> |
| 368 | <td> |
| 369 | <code><a href="/search?q=faved_by%3aTeaspoon">faved_by:Teaspoon</a> |
| 370 | </code></td> |
| 371 | </tr> |
| 372 | <tr> |
| 373 | <td> |
| 374 | <code>faves</code> |
| 375 | </td> |
| 376 | <td>Numeric Range</td> |
| 377 | <td>Matches any image with the specified number of favorites.</td> |
| 378 | <td> |
| 379 | <code><a href="/search?q=faves%3a20">faves:20</a> |
| 380 | </code></td> |
| 381 | </tr> |
| 382 | <tr> |
| 383 | <td> |
| 384 | <code>height</code> |
| 385 | </td> |
| 386 | <td>Numeric Range</td> |
| 387 | <td>Matches any image with the specified height.</td> |
| 388 | <td> |
| 389 | <code><a href="/search?q=height%3a1080">height:1080</a> |
| 390 | </code></td> |
| 391 | </tr> |
| 392 | <tr> |
| 393 | <td> |
| 394 | <code>id</code> |
| 395 | </td> |
| 396 | <td>Numeric Range</td> |
| 397 | <td>Matches any image with the specified number.</td> |
| 398 | <td> |
| 399 | <code><a href="/search?q=id%3a111111">id:111111</a> |
| 400 | </code></td> |
| 401 | </tr> |
| 402 | <tr> |
| 403 | <td> |
| 404 | <code>orig_sha512_hash</code> |
| 405 | </td> |
| 406 | <td>Literal</td> |
| 407 | <td> |
| 408 | Matches the |
| 409 | <em>original</em> SHA-512 checksum of an uploaded image. |
| 410 | </td> |
| 411 | <td> |
| 412 | <code><a href=""></a> |
| 413 | </code></td> |
| 414 | </tr> |
| 415 | <tr> |
| 416 | <td> |
| 417 | <code>score</code> |
| 418 | </td> |
| 419 | <td>Numeric Range</td> |
| 420 | <td>Matches any image with the specified net score.</td> |
| 421 | <td> |
| 422 | <code><a href="/search?q=score.gt%3a200">score.gt:200</a> |
| 423 | </code></td> |
| 424 | </tr> |
| 425 | <tr> |
| 426 | <td> |
| 427 | <code>sha512_hash</code> |
| 428 | </td> |
| 429 | <td>Literal</td> |
| 430 | <td> |
| 431 | Matches any image with the specified SHA-512 checkusm. N.B.: Image optimization usually alters the original checksum! |
| 432 | </td> |
| 433 | <td> |
| 434 | <code><a href=""></a> |
| 435 | </code></td> |
| 436 | </tr> |
| 437 | <tr> |
| 438 | <td> |
| 439 | <code>source_url</code> |
| 440 | </td> |
| 441 | <td>Literal</td> |
| 442 | <td> |
| 443 | Matches image source URLs. Case-insensitive. |
| 444 | </td> |
| 445 | <td> |
| 446 | <code><a href="/search?q=source_url%3a%2adeviantart.com%2a">source_url:*deviantart.com*</a> |
| 447 | </code></td> |
| 448 | </tr> |
| 449 | <tr> |
| 450 | <td> |
| 451 | <code>tag_count</code> |
| 452 | </td> |
| 453 | <td>Numeric Range</td> |
| 454 | <td>Matches any image with the specified number of tags</td> |
| 455 | <td> |
| 456 | <code><a href="/search?q=tag_count.gt%3a10">tag_count.gt:10</a> |
| 457 | </code></td> |
| 458 | </tr> |
| 459 | <tr> |
| 460 | <td> |
| 461 | <code>uploader</code> |
| 462 | </td> |
| 463 | <td>Literal</td> |
| 464 | <td>Matches any image with the specified uploader account. Case-insensitive.</td> |
| 465 | <td> |
| 466 | <code><a href="/search?q=uploader%3aTeaspoon">uploader:Teaspoon</a> |
| 467 | </code></td> |
| 468 | </tr> |
| 469 | <tr> |
| 470 | <td> |
| 471 | <code>upvotes</code> |
| 472 | </td> |
| 473 | <td>Numeric Range</td> |
| 474 | <td>Matches any image with the specified upvote count.</td> |
| 475 | <td> |
| 476 | <code><a href="/search?q=upvotes.gt%3a200">upvotes.gt:200</a> |
| 477 | </code></td> |
| 478 | </tr> |
| 479 | <tr> |
| 480 | <td> |
| 481 | <code>width</code> |
| 482 | </td> |
| 483 | <td>Numeric Range</td> |
| 484 | <td>Matches any image with the specified width.</td> |
| 485 | <td> |
| 486 | <code><a href="/search?q=width%3a1920">width:1920</a> |
| 487 | </code></td> |
| 488 | </tr> |
| 489 | <tr> |
| 490 | <td> |
| 491 | <code>wilson_score</code> |
| 492 | </td> |
| 493 | <td>Numeric Range</td> |
| 494 | <td>Matches any image with the specified lower bound of a 99.5% Wilson CI.</td> |
| 495 | <td> |
| 496 | <code><a href="/search?q=wilson_score.gt%3a0.9">wilson_score.gt:0.9</a> |
| 497 | </code></td> |
| 498 | </tr> |
| 499 | </tbody> |
| 500 | </table> |
| 501 | <p> |
| 502 | It is worth noting the absence of certain “fields” such as |
| 503 | <code>artist</code> and |
| 504 | <code>oc</code>. These are |
| 505 | <em>tag namespaces,</em> not metadata, but they are functionally the same. Thus, a search for |
| 506 | <code><a href="/search?q=oc%3Afreckles">oc:freckles</a> |
| 507 | </code> performs as expected. |
| 508 | </p> |
| 509 | <h2 id="special-charcters">Special Characters and Suffixes</h2> |
| 510 | <h3 id="wildcards">Wildcards</h3> |
| 511 | <p> |
| 512 | Wildcards allow for matching with terms that begin with, end with, or contain a given string of characters, like wildcards used in file management. Two wildcards are recognized: the asterisk (or star) and the question mark. |
| 513 | </p> |
| 514 | <p> |
| 515 | A question mark matches to a single character in its place, including none. For example, |
| 516 | <code><a href="/search?q=%3Fox">*ox</a> |
| 517 | </code> matches to uploads with any of the tags |
| 518 | <code>box</code>, |
| 519 | <code>fox</code>, and simply |
| 520 | <code>ox</code>. |
| 521 | </p> |
| 522 | <p> |
| 523 | An asterisk matches to any character in its place. For example, |
| 524 | <code><a href="/search?q=*glasses">*glasses</a> |
| 525 | </code> can match to either |
| 526 | <code>glasses</code> or |
| 527 | <code>sunglasses</code>. |
| 528 | </p> |
| 529 | <table class="table"> |
| 530 | <thead> |
| 531 | <tr> |
| 532 | <th>Wildcard Character</th> |
| 533 | <th>Match</th> |
| 534 | </tr> |
| 535 | </thead> |
| 536 | <tbody> |
| 537 | <tr> |
| 538 | <td> |
| 539 | <code>*</code> |
| 540 | </td> |
| 541 | <td>Zero or more characters</td> |
| 542 | </tr> |
| 543 | <tr> |
| 544 | <td> |
| 545 | <code>?</code> |
| 546 | </td> |
| 547 | <td>A single character</td> |
| 548 | </tr> |
| 549 | </tbody> |
| 550 | </table> |
| 551 | <h3 id="escaping">Escaping Special Characters</h3> |
| 552 | <p> |
| 553 | The use of special characters that modify search terms or exist outside search terms mandates a facility for “escaping” those characters, so that they are not excluded from search terms themselves. To use special characters within a search |
| 554 | term, both of the conventional string escaping mechanisms are used: the backslash and quoting. The following are special characters and sequences that may need to be escaped: |
| 555 | </p> |
| 556 | <ul> |
| 557 | <li> |
| 558 | <code>( |
| 559 | </code></li> |
| 560 | <li> |
| 561 | <code>) |
| 562 | </code></li> |
| 563 | <li> |
| 564 | <code>*</code> |
| 565 | </li> |
| 566 | <li> |
| 567 | <code>?</code> |
| 568 | </li> |
| 569 | <li> |
| 570 | <code>-</code> (when placed in front of a term) |
| 571 | </li> |
| 572 | <li> |
| 573 | <code>!</code> (when placed in front of a term) |
| 574 | </li> |
| 575 | <li> |
| 576 | <code>,</code> |
| 577 | </li> |
| 578 | <li> |
| 579 | <code>&&</code> |
| 580 | </li> |
| 581 | <li> |
| 582 | <code>||</code> |
| 583 | </li> |
| 584 | <li> |
| 585 | <code>OR</code> (if all-capitalized) |
| 586 | </li> |
| 587 | <li> |
| 588 | <code>AND</code> (if all-capitalized) |
| 589 | </li> |
| 590 | <li> |
| 591 | <code>NOT</code> (if all-capitalized) |
| 592 | </li> |
| 593 | <li> |
| 594 | <code>"</code> |
| 595 | </li> |
| 596 | <li> |
| 597 | <code>\</code> |
| 598 | </li> |
| 599 | <li> |
| 600 | <code>~</code> (with <a href="#fuzzy">fuzzy matching syntax</a>) |
| 601 | </li> |
| 602 | <li> |
| 603 | <code>^</code> (with <a href="#boosting">boosting</a>) |
| 604 | </li> |
| 605 | </ul> |
| 606 | <p> |
| 607 | A backslash is placed in front of a special character (and can also be placed in front of a sequence like the ones in the preceding list). This forces a given character to be counted as part of the preceding or following term. In front of any other character, |
| 608 | it effectively has no effect. For example, |
| 609 | <code><a href="/search?q=%5c%2d_%2d">\-_-</a> |
| 610 | </code> forces a search for the emoticon |
| 611 | <code>-_-</code>, despite it following the syntax for |
| 612 | <code><a href="#negation">negation</a> |
| 613 | </code> if without the backslash. Also consider the search term |
| 614 | <code><a href="/search?q=frog+%5c%28hoof%5c%29">frog \(hoof\)</a></code>, although parentheses have intuitive rules that do not make escaping them necessary in most cases. The backslash is a special character and thus must also be escaped; a literal |
| 615 | backslash is indicated with <code>\\</code>. |
| 616 | </p> |
| 617 | <p> |
| 618 | The alternative to escaping is to simply surround the search query in double quotes (<code>"</code>), e.g., |
| 619 | <code><a href="/search?q=%22frog+%28hoof%29%22">"frog (hoof)"</a></code>. When searching with a specified field, quotes |
| 620 | <strong>must surround the field and colon as well</strong>, e.g., |
| 621 | <code><a href="/search?q=%22faved_by%3ak_a%22">"width:1920"</a></code>. Eveything in quotes is together treated as a verbatim search term, with one exception. Note that the double quote character itself bounds the search term, so if it appears inside, |
| 622 | it must be escaped with a backslash. |
| 623 | <strong>All other uses of backslash are treated literally.</strong> |
| 624 | </p> |
| 625 | <h3 id="fuzzy">Approximate (Fuzzy) String Matching</h3> |
| 626 | <p> |
| 627 | The search engine backend, Apache Lucene, also enables so-called “fuzzy” string matching. Fuzzy string matching can be used with any literal search term, including the default tags field. A fuzzy match is specified using a similarity metric |
| 628 | either ranging from 0 to 1.0 or a whole number. The whole number specifies an |
| 629 | <i>optimal string alignment edit distance,</i> which is the maximum number of edits done to a string to match a given target, with an edit defined as a deletion, insertion, replacement, or switching two adjacent characters. One may alternatively define |
| 630 | a similarity factor ranging from 0 to 1.0, with a 1.0 the least “fuzzy”. The derived edit distance is the length of the term sans the field name prefix, multiplied by the difference of unity minus the similarity factor, all rounded down. |
| 631 | To specify either, a term is followed with a tilde followed by the edit distance or similarity factor. |
| 632 | <strong> |
| 633 | Note in both cases that Lucene caps the maximum edit distance at 2, as an |
| 634 | optimization. Therefore, very large edit distances or small similarities |
| 635 | will not behave as expected. |
| 636 | </strong></p> |
| 637 | <p> |
| 638 | For example, |
| 639 | <code><a href="/search?q=equina%7e1.0">equina~0.8</a> |
| 640 | </code> searches for uploads with tags that approximately match |
| 641 | <code>equina</code>, with a similairty of 0.8. This is an edit distance of ⌊(1 − 0.8)(10)⌋ = 2. Note that uploads tagged |
| 642 | <code>equine</code> are included in the result set. The utility of this is obvious: if you are unsure of a character or tag's exact spelling, you can use this as an aid, like a more manual and controlled version of Google's (in)famous spelling correction |
| 643 | features. |
| 644 | </p> |
| 645 | <p> |
| 646 | Fuzziness can also be applied to numeric queries to specify a range. In this case, the fuzziness parameter is the magnitude above and below the specified number that will be included in the result set. For example, |
| 647 | <code><a href="/search?q=width%3a800%7e200">width:800~200</a> |
| 648 | </code> specifies images with a width ranging from 600 (800 − 200) to 1000 (800 + 200), inclusive. |
| 649 | </p> |
| 650 | <p> |
| 651 | Fuzzy matching can be freely applied to any term inside an |
| 652 | <code><a href="#expressions">expression</a></code>. |
| 653 | |
| 654 | </p> |
| 655 | <h2 id="grammar">Search Grammar: Term Operators and Combinations</h2> |
| 656 | <h3 id="expressions">Expressions</h3> |
| 657 | <p> |
| 658 | Terms can be combined to define a search query corresponding to a specific result set. These combinations are formulized as |
| 659 | <b>expressions</b> that are constructed from terms, operators, and even other expressions, which are then called |
| 660 | <strong>subexpressions</strong>. Expressions recognized by the search frontend are the negation of a term or subexpression, the requirement of any search term or subexpression, or the requirement of both search terms or subexpressions. |
| 661 | </p> |
| 662 | <p> |
| 663 | At its core, a search expression is either |
| 664 | <strong>binary</strong> or <strong>unary</strong>. A binary expression consists of a term or subexpression, an |
| 665 | <strong>operator</strong> indicating the type of expression, and another term or subexpression. Binary expressions can be “chained” by adding the operator followed by another term. A unary expression consists of the operator followed by |
| 666 | a single term or subexpression. Both expression types and how to use subexpressions will be covered in the following sections. |
| 667 | </p> |
| 668 | <h3 id="expressions-summary">Summary Table</h3> |
| 669 | <table class="table"> |
| 670 | <thead> |
| 671 | <tr> |
| 672 | <th>Operator</th> |
| 673 | <th>Symbols</th> |
| 674 | <th>Comments</th> |
| 675 | </tr> |
| 676 | </thead> |
| 677 | <tbody> |
| 678 | <tr> |
| 679 | <td>Negation (NOT)</td> |
| 680 | <td> |
| 681 | <ul> |
| 682 | <li> |
| 683 | <code>NOT</code> |
| 684 | </li> |
| 685 | <li> |
| 686 | <code>-</code> |
| 687 | </li> |
| 688 | <li> |
| 689 | <code>!</code> |
| 690 | </li> |
| 691 | </ul> |
| 692 | </td> |
| 693 | <td> |
| 694 | Applied in front of a single term or parenthesized subexpression. The minus sign does not require padding to the right. Specifies that the term or subexpression |
| 695 | <em>must not</em> match. |
| 696 | </td> |
| 697 | </tr> |
| 698 | <tr> |
| 699 | <td>Conjunction (AND)</td> |
| 700 | <td> |
| 701 | <ul> |
| 702 | <li> |
| 703 | <code>,</code> |
| 704 | </li> |
| 705 | <li> |
| 706 | <code>&&</code> |
| 707 | </li> |
| 708 | <li> |
| 709 | <code>AND</code> |
| 710 | </li> |
| 711 | </ul> |
| 712 | </td> |
| 713 | <td> |
| 714 | Applied between two terms. The comma may be optionally padded with space on either side; the other forms must be padded. Specifies that both terms match. Can be chained to more terms. |
| 715 | </td> |
| 716 | </tr> |
| 717 | <tr> |
| 718 | <td>Disjunction (OR)</td> |
| 719 | <td> |
| 720 | <ul> |
| 721 | <li> |
| 722 | <code>||</code> |
| 723 | </li> |
| 724 | <li> |
| 725 | <code>OR</code> |
| 726 | </li> |
| 727 | </ul> |
| 728 | </td> |
| 729 | <td> |
| 730 | Applied between two terms, with surrounding space. Specifies that either of the terms match. Can be chained to more terms. |
| 731 | </td> |
| 732 | </tr> |
| 733 | </tbody> |
| 734 | </table> |
| 735 | <h3 id="negation">Negation</h3> |
| 736 | <p> |
| 737 | <b>Negation</b> of a term or expression specifies that the the original term or subexpression |
| 738 | <em>must not</em> match. The corresponding negation operator is |
| 739 | <b>unary</b>, that is, applied to either a single term or to a subexpression. It is specified with the all-capitalized word |
| 740 | <code>NOT</code>, a dash of the non-multi-chromatic variety (<code>-</code>), or an exclamation point (<code>!</code>). For example, |
| 741 | <code><a href="/search?q=%2dequine">-equine</a></code> or <code><a href="/search?q=NOT+equine">NOT equine</a></code> matches pictures that are |
| 742 | <em>not</em> tagged with |
| 743 | <code>equine</code>. In set theory terms, this is taking the |
| 744 | <em>complement</em> of the original result set, that is, all uploads outside it. |
| 745 | </p> |
| 746 | <h3 id="and-expressions">Commas and AND Expressions</h3> |
| 747 | <p> |
| 748 | An expression that queries for images that meet |
| 749 | <em>all</em> specified terms is a |
| 750 | <b>conjunction</b> or |
| 751 | <b>AND expresssion</b>. As in the past, you can query images that meet a list of terms by hooking the terms together with commas. For example, |
| 752 | <code><a href="/search?q=equine%2ccanine">equine,canine</a> |
| 753 | </code> results in pictures that contain |
| 754 | <em>both</em> the |
| 755 | <code>fluttersy</code> and |
| 756 | <code>canine</code> tags. In set theory terms, the result set is the intersection of uploads tagged |
| 757 | <code>equine</code> and uploads tagged |
| 758 | <code>canine</code>. |
| 759 | </p> |
| 760 | <p> |
| 761 | Commas can be padded with spaces however you like. Unlike the past, commas are now plain AND operators, so they are more versatile. As will be discussed, they can be used in subexpressions and alongside the OR operator. |
| 762 | </p> |
| 763 | <p> |
| 764 | AND operators can also be expressed using |
| 765 | <code>&&</code> (derived from typical programming notation) or the all-capitalized word |
| 766 | <code>AND</code>, e.g., |
| 767 | <code><a href="/search?q=feral+%26%26+canine">feral && canine</a></code> or |
| 768 | <code><a href="/search?q=feral+AND+canine">feral AND canine</a></code>. These forms, unlike the comma, require padding space on either side. |
| 769 | </p> |
| 770 | <h3 id="or-expressions">OR Expressions</h3> |
| 771 | <p> |
| 772 | A |
| 773 | <b>disjunction</b> or |
| 774 | <b>OR expression</b> requests for uploads that meet |
| 775 | <em>any</em> of the specified search terms. This is markedly different from the aforementioned AND expression, which, to reiterate, mandates that |
| 776 | <em>all</em> terms match. OR operators are expressed either with |
| 777 | <code>||</code> (also a programming notation) or the all-capitalized word |
| 778 | <code>OR</code>, e.g., |
| 779 | <code><a href="/search?q=feral+%7c%7c+canine">feral || canine</a></code> or |
| 780 | <code><a href="/search?q=feral+OR+canine">feral OR canine</a></code>. In set theory terms, the result set is the union of uploads tagged |
| 781 | <code>feral</code> and uploads tagged |
| 782 | <code>canine</code>. All forms of the OR operator require padding on either side. |
| 783 | </p> |
| 784 | <h3 id="compound">Compound Expressions</h3> |
| 785 | <p> |
| 786 | Complex combinations of terms, and therefore search criteria, are possible by combining expressions together. Doing so effectively is analogous to arithmetic. Consider multiplication and addition (which in so-called |
| 787 | <em>Boolean alegra</em> are respectively analogous to AND and OR operations). We can express an algebraic expression with multiplication and addition several ways. For three terms, |
| 788 | <i>A</i>, |
| 789 | <i>B</i>, and |
| 790 | <i>C</i>, consider the expression |
| 791 | <i>A</i> × |
| 792 | <i>B</i> + |
| 793 | <i>C</i>. Multiplication is evaluated before addition, so this expression is equivalent to (<i>A</i> × |
| 794 | <i>B</i>) + |
| 795 | <i>C,</i> in which case the order of operations is explicit. |
| 796 | </p> |
| 797 | <h4 id="precedence">Operator Precedence</h4> |
| 798 | <p> |
| 799 | Likewise, precedence is applied to determine the order in which chained OR, AND, and NOT operations are evaluated. The order of operations in the search syntax is as follows: |
| 800 | </p> |
| 801 | <ol> |
| 802 | <li>negation (NOT)</li> |
| 803 | <li>conjunction (AND)</li> |
| 804 | <li>disjunction (OR)</li> |
| 805 | </ol> |
| 806 | <p> |
| 807 | Consider the query |
| 808 | <code><a href="/search?q=smiling+%7c%7c+equine+%26%26+canine">smiling || equine && canine</a></code>. In this example, |
| 809 | <code>equine && canine</code> is evaluated first, as an implicit |
| 810 | <em>subexpression.</em> Then, that result is OR'd together with |
| 811 | <code>smiling</code>. Thus, the query instructs the engine to return uploads |
| 812 | <em>either</em> tagged with |
| 813 | <code>smiling</code> |
| 814 | <em>or</em> tagged with |
| 815 | <em>both</em> |
| 816 | <code>equine</code> |
| 817 | <em>and</em> |
| 818 | <code>canine</code>. Note how if the OR expression |
| 819 | <code>smiling || equine</code> were evaluated first, the result set would differ. |
| 820 | </p> |
| 821 | <h4 id="parentheses">Defining Subexpressions with Parentheses</h4> |
| 822 | <p> |
| 823 | Returning to an earlier example with arithmetic, we can trump the order of operations using explicit subexpressions. This requires the use of |
| 824 | <em>delimiters</em> that act as boundaries, and most often parentheses are used for this purpose. Hence, |
| 825 | <i>A</i> × (<i>B</i> + |
| 826 | <i>C</i>) forces |
| 827 | <i>B</i> + |
| 828 | <i>C</i> to be evaluated, and then multiplied with |
| 829 | <i>A</i>, which is contrary to the order otherwise followed. Likewise, |
| 830 | <code><a href="/search?q=%28smiling+%7c%7c+equine%29+%26%26+canine">(smiling || equine) && canine</a> |
| 831 | </code> instructs the search engine to return results that have |
| 832 | <em>either</em> |
| 833 | <code>smiling</code> |
| 834 | <em> or</em> |
| 835 | <code>equine</code> |
| 836 | <em>and always match</em> the tag |
| 837 | <code>canine</code>. |
| 838 | </p> |
| 839 | <p> |
| 840 | As was mentioned earlier, the unary NOT operator can be applied to parenthesized subexpressions. The semantics of this is analogous to applying it to a single term: a negated subexpression specifies uploads that |
| 841 | <em>do not</em> adhere to what the subexpression specifies. For example, the query |
| 842 | <code><a href="/search?q=-%28blood%2C+grimdark%29">-(blood, grimdark)</a> |
| 843 | </code> returns all uploads that are |
| 844 | <em>not</em> tagged with |
| 845 | <em>both</em> |
| 846 | <code>blood</code> |
| 847 | <em>and</em> |
| 848 | <code>grimdark</code>. Uploads tagged with |
| 849 | <em>either</em> of the two would be returned as long as they do not have both. Thus safe images with blood and grimdark material not showing blood would be included, yet the intersection of those two sets of images would be excluded, that |
| 850 | is, images that are grimdark and contain blood. |
| 851 | </p> |
| 852 | <p> |
| 853 | Explicit subexpressions with parentheses allow for complex queries as they can be arbitrarily nested inside other subexpressions, to fine-tune the result set even more. |
| 854 | </p> |
| 855 | <h4 id="auto-escaping">Automatic Parentheses Escaping</h4> |
| 856 | <p> |
| 857 | Finally, a footnote about paretheses is warranted. Traditionally, if an expression parser encounters an open parenthesis without a closing parenthesis, or if parentheses are swapped, an error is raised. This is indeed the case with the search engine, |
| 858 | as highlighted in the search parsing error page. However, to a limited extent, a term can contain parentheses within. Parentheses are accepted within search terms as long as they are closed and do not cover the entire expression. The first limit is |
| 859 | a heuristic to address the typical use of parentheses, and the latter arises from the legal use of parentheses to single out a term. Thus, the search |
| 860 | <code><a href="/search?q=frog+%28hoof%29">frog (hoof)</a> |
| 861 | </code> searches for uploads tagged with |
| 862 | <code>frog (hoof)</code> ; however, the emoticon query |
| 863 | <code><a href="/search?q=%29%29B-%28">))B-(</a> |
| 864 | </code> raises an error, while |
| 865 | <code><a href="/search?q=%28q%29">(q)</a> |
| 866 | </code> effectively searches for |
| 867 | <code>q</code>, instead. For the latter two examples, simply surround with double quotes to clarify your meaning to the search engine. |
| 868 | </p> |
| 869 | <h2 id="boosting">Boosting Terms</h2> |
| 870 | <p> |
| 871 | The search engine also allows the boosting of specific terms when sorting by relevance, so that uploads including or not including the term occur earlier or later in the results. Boosting is done by modifying a term's relevance score with a positive or |
| 872 | negative value. This value is affixed to a term with a preceding caret (<code>^</code>) and with a positive or negative decimal number. For example, |
| 873 | <code><a href="/search?q=canine%5e1+%7c%7c+dog&sf=relevance&sd=desc">canine^1 || dog</a> |
| 874 | </code> returns uploads tagged either with |
| 875 | <code>canine</code> or |
| 876 | <code>dog</code>, but when sorting by relevance descending, uploads with |
| 877 | <code>canine</code> are prioritized. A negative value meanwhile reduces the relevance score and deprioritizes the affected term when sorting by relevance, e.g., |
| 878 | <code><a href="/search?q=canine%5e1+%7c%7c+dog&sf=relevance&sd=desc">canine^-1 || dog</a></code>. Sorting options are found below the search box on this page and |
| 879 | <strong>must be set to sort by relevance</strong> for boosting to take proper effect. Thus, in both cases, pictures with |
| 880 | <em>both</em> tags will still appear first. |
| 881 | </p> |
