> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 搜索运算符

X 搜索运算符是特殊关键词和符号，可按作者、日期、互动、媒体类型、语言、位置等属性筛选推文。本页大多数运算符可用于[搜索推文](https://docs.sorsa.io/zh-Hans/api-reference/search/search-tweets)端点的 `query` 字段，也可用于 x.com。少数标注为仅界面可用的运算符依赖登录账号的信息，例如关注对象、所在地和社交网络，因此不能通过 API 使用。

> **注意：** 如需可直接复制的查询方案、包含分页的 Python/JavaScript 生产代码，以及与官方 X API v2 运算符的并排比较，请参阅博客上的 [Twitter 搜索运算符完整速查表](https://api.sorsa.io/blog/twitter-search-operators)。

## 基础语法

* 词语之间的空格表示**隐式 AND**
* `OR` 必须**大写**
* 在前面加减号（`-`）可**排除**词语、短语或运算符条件
* 使用**括号**对表达式分组
* 使用**双引号**包围精确短语

运算符可以自由组合，每个查询大约最多 22–23 个。AND 的优先级高于 OR：`cat OR black dog` 会按 `cat OR (black dog)` 处理。请用括号消除歧义。

## 免费可视化查询构建器

不想手动组合运算符字符串时，可以使用 [Sorsa 搜索构建器](https://api.sorsa.io/playground/search-builder)。这是无需登录的免费图形工具，可切换筛选条件并预览生成的查询字符串，再将它集成到代码中。

***

## 1. 关键词与布尔逻辑

| 运算符                  | 说明                      | 示例                                   |
| :------------------- | :---------------------- | :----------------------------------- |
| `keyword keyword`    | 包含两个词的推文（隐式 AND）。       | `nasa esa`                           |
| `keyword OR keyword` | 包含任一词的推文。`OR` 必须大写。     | `bitcoin OR ethereum`                |
| `"exact phrase"`     | 包含精确短语的推文，同时防止自动纠错。     | `"state of the art"`                 |
| `-keyword`           | 排除包含该词、短语或运算符条件的推文。     | `crypto -scam`                       |
| `( )`                | 将词语分组，以构建复杂布尔逻辑。        | `(AI OR "machine learning") lang:en` |
| `"word * word"`      | 引号内短语的通配符。`*` 代替任意一个单词。 | `"this is the * time"`               |
| `+word`              | 强制精确匹配，防止自动纠错和词干处理。     | `+radiooooo`                         |
| `#hashtag`           | 匹配特定话题标签。               | `#tgif`                              |
| `$cashtag`           | 匹配股票或加密货币符号。            | `$TSLA`                              |

单复数形式会相互匹配。运算符会匹配推文正文、作者显示名称、用户名以及推文中展开后的 URL。

***

## 2. 用户与账号筛选

| 运算符                    | 说明                                | 示例                            |
| :--------------------- | :-------------------------------- | :---------------------------- |
| `from:username`        | 指定账号发布的推文，用户名不含 @。                | `from:elonmusk`               |
| `to:username`          | 回复指定账号的推文。                        | `to:openai`                   |
| `@username`            | 正文任意位置提及指定账号的推文。                  | `@sorsa_app`                  |
| `list:ID`              | 公开 X 列表成员的推文。使用 URL 中的数字列表 ID。    | `list:715919216927322112`     |
| `filter:verified`      | 仅限旧版认证账号（2023 年之前的蓝色认证标记）。        | `AI filter:verified`          |
| `filter:blue_verified` | 仅限 X Premium（付费 Blue）订阅者。         | `crypto filter:blue_verified` |
| `filter:follows`       | 仅限你关注的账号。只适用于网页界面，不能取反。           | `filter:follows`              |
| `filter:social`        | 来自算法扩展社交网络的内容。适用于“热门”结果，不适用于“最新”。 | `filter:social`               |

***

## 3. 互动门槛

| 运算符                     | 说明                     | 示例                                    |
| :---------------------- | :--------------------- | :------------------------------------ |
| `min_faves:N`           | 最少点赞数。                 | `AI min_faves:100`                    |
| `min_retweets:N`        | 最少转推数。                 | `crypto min_retweets:50`              |
| `min_replies:N`         | 最少回复数。                 | `"product launch" min_replies:20`     |
| `-min_faves:N`          | 最多点赞数（取反形式）。           | `bitcoin -min_faves:1000`             |
| `-min_retweets:N`       | 最多转推数。                 | `news -min_retweets:500`              |
| `-min_replies:N`        | 最多回复数。                 | `tech -min_replies:100`               |
| `filter:has_engagement` | 至少有一次互动的推文。取反可查找零互动推文。 | `from:username filter:has_engagement` |

数值很大时（1,000 以上），计数会变为近似值。

***

## 4. 媒体与内容类型

### 媒体筛选

| 运算符                      | 说明                                                  |
| :----------------------- | :-------------------------------------------------- |
| `filter:media`           | 所有媒体类型（图片、视频、GIF）。                                  |
| `filter:images`          | 所有图片，包括第三方链接。                                       |
| `filter:twimg`           | 仅原生 X 图片（`pic.twitter.com` 链接）。                     |
| `filter:videos`          | 所有视频类型：原生 X 视频、YouTube 嵌入等。                         |
| `filter:native_video`    | 仅 X 所属视频（原生上传、旧版 Vine、旧版 Periscope）。                |
| `filter:consumer_video`  | 仅 X 原生视频，不含 pro/Amplify。                            |
| `filter:pro_video`       | 仅 X pro 视频（Amplify）。                                |
| `filter:spaces`          | X Spaces 音频内容。                                      |
| `filter:links`           | 包含任意 URL 的推文，包括媒体 URL。配合 `-filter:media` 可仅保留非媒体链接。 |
| `card_name:animated_gif` | 专门匹配 GIF。                                           |

### 推文类型筛选

| 运算符                      | 说明                     |
| :----------------------- | :--------------------- |
| `filter:replies`         | 仅保留回复其他推文的推文。          |
| `-filter:replies`        | 排除回复，仅显示顶层原创推文。        |
| `filter:nativeretweets`  | 仅原生转推，即通过转推按钮创建的转推。    |
| `include:nativeretweets` | 在结果中包含原生转推，默认不包含。      |
| `filter:retweets`        | 旧式 RT 转推及引用推文。         |
| `-filter:retweets`       | 完全排除转推。                |
| `filter:quote`           | 仅引用推文。                 |
| `quoted_tweet_id:ID`     | 按 ID 查找指定推文的引用。        |
| `quoted_user_id:ID`      | 按用户 ID 查找对指定用户的所有引用。   |
| `conversation_id:ID`     | 对话串中的全部推文，包括直接回复和嵌套回复。 |

### 特殊内容筛选

| 运算符                               | 说明                          |
| :-------------------------------- | :-------------------------- |
| `card_name:poll2choice_text_only` | 两个选项的文字投票。                  |
| `card_name:poll3choice_text_only` | 三个选项的文字投票。                  |
| `card_name:poll4choice_text_only` | 四个选项的文字投票。                  |
| `card_name:poll2choice_image`     | 两个选项的图片投票。                  |
| `filter:news`                     | 链接到已识别新闻域名的推文。              |
| `filter:safe`                     | 排除 NSFW 或可能敏感的内容，但不能保证完全过滤。 |
| `filter:hashtags`                 | 仅包含至少一个话题标签的推文。             |
| `filter:mentions`                 | 仅包含任意 @提及的推文。               |

***

## 5. 日期、时间与 Snowflake ID

| 运算符                             | 格式                              | 说明                           |
| :------------------------------ | :------------------------------ | :--------------------------- |
| `since:YYYY-MM-DD`              | `since:2026-01-01`              | 在此日期或之后发布的推文（包含当天）。          |
| `until:YYYY-MM-DD`              | `until:2026-03-01`              | 在此日期之前发布的推文（不包含当天）。          |
| `since:YYYY-MM-DD_HH:MM:SS_UTC` | `since:2026-03-05_12:00:00_UTC` | 带时区的精确时间戳。                   |
| `since_time:UNIX`               | `since_time:1142974200`         | 在指定 Unix 时间戳（秒）之后。           |
| `until_time:UNIX`               | `until_time:1142974215`         | 在指定 Unix 时间戳之前。              |
| `within_time:Xd`                | `within_time:2d`                | 最近 X 天内，也支持 `h`、`m`、`s`。     |
| `since_id:ID`                   | `since_id:1234567890`           | 在指定 Snowflake ID 之后，不包含该 ID。 |
| `max_id:ID`                     | `max_id:1234567890`             | 小于或等于指定 Snowflake ID，包含该 ID。 |

**Snowflake ID 转换。** 每条推文 ID 都编码了创建时间戳：

```text theme={null}
millisecond_epoch = (tweet_id >> 22) + 1288834974657
```

获取历史数据集的方法见[历史数据](https://docs.sorsa.io/zh-Hans/historical-data)。

***

## 6. 地理位置筛选

| 运算符                       | 说明                             | 示例                                  |
| :------------------------ | :----------------------------- | :---------------------------------- |
| `near:"city"`             | 地理标记位于指定地点附近，支持短语。             | `near:"San Francisco"`              |
| `near:me`                 | 当前位置附近，仅界面可用。                  | `near:me`                           |
| `within:Xkm`              | 为 `near:` 设置半径，支持 `km` 或 `mi`。 | `earthquake near:Tokyo within:50km` |
| `geocode:lat,long,radius` | 通过坐标精确定位。                      | `geocode:37.77,-122.41,5km`         |
| `place:ID`                | 按 X Place 对象 ID 搜索。            | `place:96683cc9126741d1`            |

据估计，只有 1%–2% 的推文带有精确地理位置数据。如果推文没有坐标，API 会退而使用用户资料中的所在地进行反向地理编码。

***

## 7. 语言与来源

### 语言

支持标准 ISO 639-1 代码（`lang:en`、`lang:es`、`lang:fr`、`lang:de`、`lang:ja`、`lang:ru` 等），以及以下 X 专用代码：

| 代码         | 含义                          |
| :--------- | :-------------------------- |
| `lang:und` | 未定义语言，例如仅含表情符号或媒体的推文。       |
| `lang:qme` | 仅含媒体链接的推文，自 2022 年起。        |
| `lang:qst` | 非常短的文本推文。                   |
| `lang:qht` | 仅含话题标签的推文。                  |
| `lang:qam` | 仅含提及的推文。                    |
| `lang:qct` | 仅含股票或加密货币符号的推文。             |
| `lang:zxx` | 仅含媒体或 Twitter Card、没有文本的推文。 |

### 来源（发帖客户端）

| 运算符                  | 说明                | 示例                          |
| :------------------- | :---------------- | :-------------------------- |
| `source:client_name` | 按发帖应用筛选，用下划线代替空格。 | `source:Twitter_for_iPhone` |

常见值：`Twitter_for_iPhone`、`Twitter_for_Android`、`Twitter_Web_App`、`TweetDeck`、`twitter_ads`。

***

## 8. 卡片与 URL 运算符

| 运算符                             | 说明                                                |
| :------------------------------ | :------------------------------------------------ |
| `card_domain:domain`            | 匹配 Twitter Card 中的域名，大致等同于 `url:`。                |
| `card_url:domain`               | 类似 `card_domain:`，但结果可能不同。                        |
| `card_name:audio`               | 包含播放器卡片的推文，如 Spotify、SoundCloud 等。                |
| `card_name:player`              | 包含任意播放器卡片的推文。                                     |
| `card_name:summary`             | 小图摘要卡片。                                           |
| `card_name:summary_large_image` | 大图摘要卡片。                                           |
| `card_name:promo_website`       | 推广网站卡片。                                           |
| `card_name:promo_image_convo`   | 带图片的对话式广告卡片。                                      |
| `card_name:promo_video_convo`   | 带视频的对话式广告卡片。                                      |
| `url:domain`                    | 匹配 URL，适用于域名和子域名。用下划线代替连字符，例如 `url:t_mobile.com`。 |

`card_name:` 通常只匹配最近 7–8 天的推文。

***

## 构建查询

建议按以下顺序组合查询，便于扩展：

1. **组合核心关键词：**`(bitcoin OR ethereum OR $BTC)`
2. **添加内容条件：**`lang:en`、`filter:images`、`-filter:replies`
3. **设置互动门槛：**`min_faves:50`、`min_retweets:10`
4. **排除噪声：**`-from:spambot`、`-scam`、`-filter:retweets`
5. **添加时间范围：**`since:2026-01-01 until:2026-03-01`

完整代码示例（含分页和速率限制处理的 Python 与 JavaScript）及 14 个生产可用查询方案，请参阅[博客完整指南](https://api.sorsa.io/blog/twitter-search-operators)。

***

## 已知限制

* **运算符数量上限：** 每个查询约 22–23 个。
* **地理数据覆盖有限：** 仅 1%–2% 的推文有精确位置。
* **`card_name:` 有时间限制：** 仅最近 7–8 天。
* **私有和被停用账号**不会出现在搜索结果中。
* 对短推文、代码或大量表情符号的帖子，**语言检测并不完美**。
* **并非所有推文都被索引。** 被标记违反平台规则的推文可能被排除。
* 某些情况下会发生**静默自动纠错**。使用 `+word` 或 `"word"` 强制精确匹配。
* **URL 匹配**适用于域名和子域名，但对较长 URL 路径不可靠。

***

## 来源

本参考依据 Igor Brigadir 持续维护的 [twitter-advanced-search 仓库](https://github.com/igorbrigadir/twitter-advanced-search)，该仓库是未公开 X 搜索行为的常用权威资料。

***

## 后续步骤

* [搜索推文](https://docs.sorsa.io/zh-Hans/search-tweets)：`/search-tweets` 端点的完整指南
* [追踪提及](https://docs.sorsa.io/zh-Hans/search-mentions)：追踪任意账号 @提及的策略
* [分页](https://docs.sorsa.io/zh-Hans/pagination)：逐页获取大型结果集
* [搜索构建器](https://api.sorsa.io/playground/search-builder)：免费可视化查询构建器
* [博客完整速查表](https://api.sorsa.io/blog/twitter-search-operators)：查询方案、代码示例和 X API v2 对比