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

# Filtered Stream 연산자

> X API v2 Filtered Stream 연산자 전체 레퍼런스로, 스트림 규칙에 사용할 수 있는 keyword, has:, is: 및 Enterprise 전용 시맨틱 embedding: 연산자를 다룹니다.

이 페이지는 Filtered Stream의 [규칙 작성](/x-api/posts/filtered-stream/integrate/build-a-rule) 시 사용할 수 있는 연산자의 전체 목록을 제공합니다.

## 개요

연산자는 특정 게시물 속성을 매칭하는 데 사용됩니다. 두 가지 유형이 있습니다:

* **독립형 연산자(Standalone operators)** — 단독으로 또는 다른 연산자와 함께 사용 가능
* **결합 필수 연산자(Conjunction-required operators)** — 최소 하나의 독립형 연산자와 함께 사용해야 함

대부분의 연산자는 Pay-per-use와 Enterprise 모두에서 사용할 수 있습니다. 시맨틱 임베딩 등 일부 고급 연산자는 추가 티어 액세스가 포함된 Enterprise가 필요합니다.

***

## 키워드 및 구문 연산자

| Operator                | Type       | Summary                           | Example                               |
| :---------------------- | :--------- | :-------------------------------- | :------------------------------------ |
| `keyword`               | Standalone | 게시물 본문 내 키워드를 매칭(토큰화된 매칭)         | `pepsi OR cola OR "coca cola"`        |
| `emoji`                 | Standalone | 게시물 본문 내 이모지를 매칭                  | `(😃 OR 😡) 😬`                       |
| `"exact phrase"`        | Standalone | 게시물 본문 내 정확한 구문을 매칭               | `("X API" OR #v2) -"filtered stream"` |
| `"keyword1 keyword2"~N` | Standalone | 근접 매칭 — 키워드 간 거리가 N 토큰 이내(최대 N=6) | `"social media"~5`                    |

***

## 엔티티 연산자

| Operator | Type       | Summary                  | Example                      |
| :------- | :--------- | :----------------------- | :--------------------------- |
| `#`      | Standalone | 해시태그를 포함한 게시물을 매칭(정확 매칭) | `#thankunext #fanart`        |
| `@`      | Standalone | 사용자명을 멘션한 게시물을 매칭        | `(@XDevelopers OR @api) -@x` |
| `$`      | Standalone | 캐시태그를 포함한 게시물을 매칭        | `$twtr OR @XDevelopers -$fb` |

***

## 사용자 연산자

| Operator             | Type       | Summary                      | Example                         |
| :------------------- | :--------- | :--------------------------- | :------------------------------ |
| `from:`              | Standalone | 특정 사용자가 작성한 게시물을 매칭          | `from:XDevelopers OR from:api`  |
| `to:`                | Standalone | 특정 사용자에 대한 답글 게시물을 매칭        | `to:XDevelopers OR to:api`      |
| `retweets_of:`       | Standalone | 특정 사용자의 리포스트를 매칭             | `retweets_of:XDevelopers`       |
| `from_affiliate_of:` | Standalone | 특정 사용자의 제휴 계정이 작성한 게시물을 매칭   | `from_affiliate_of:XDevelopers` |
| `to_affiliate_of:`   | Standalone | 특정 사용자의 제휴 계정에 대한 답글 게시물을 매칭 | `to_affiliate_of:XDevelopers`   |

***

## URL 연산자

| Operator           | Type       | Summary                                         | Example                         |
| :----------------- | :--------- | :---------------------------------------------- | :------------------------------ |
| `url:`             | Standalone | URL에 대한 토큰화된 매칭(`url` 또는 `expanded_url` 필드와 매칭) | `url:"https://developer.x.com"` |
| `url_title:`       | —          | 확장된 URL HTML 제목 메타데이터에 대한 키워드 매칭                | `url_title:snow`                |
| `url_description:` | —          | 확장된 페이지 설명 메타데이터에 대한 키워드 매칭                     | `url_description:weather`       |
| `url_contains:`    | —          | URL 내용에 대한 리터럴 매칭                               | `url_contains:photos`           |

***

## 컨텍스트 및 엔티티 연산자

| Operator           | Type       | Summary                  | Example                                           |
| :----------------- | :--------- | :----------------------- | :------------------------------------------------ |
| `context:`         | Standalone | 특정 도메인/엔티티 쌍을 가진 게시물을 매칭 | `context:10.799022225751871488` or `context:47.*` |
| `entity:`          | Standalone | 특정 엔티티 문자열 값을 가진 게시물을 매칭 | `entity:"Michael Jordan"`                         |
| `conversation_id:` | Standalone | 특정 대화 스레드의 게시물을 매칭       | `conversation_id:1334987486343299072`             |

***

## 사용자 프로필 연산자

| Operator        | Type       | Summary                | Example                                        |
| :-------------- | :--------- | :--------------------- | :--------------------------------------------- |
| `bio:`          | Standalone | 게시물 작성자의 bio 내 키워드를 매칭 | `bio:developer OR bio:"data engineer"`         |
| `bio_name:`     | Standalone | 게시물 작성자의 이름 내 키워드를 매칭  | `bio_name:phd OR bio_name:md`                  |
| `bio_location:` | Standalone | 게시물 작성자의 위치 내 키워드를 매칭  | `bio_location:"big apple" OR bio_location:nyc` |

***

## 위치 연산자

| Operator         | Type       | Summary             | Example                                                     |
| :--------------- | :--------- | :------------------ | :---------------------------------------------------------- |
| `place:`         | Standalone | 특정 위치로 태깅된 게시물을 매칭  | `place:"new york city" OR place:seattle`                    |
| `place_country:` | Standalone | 국가 코드와 일치하는 게시물을 매칭 | `place_country:US OR place_country:MX`                      |
| `point_radius:`  | Standalone | 한 지점의 반경 내 게시물을 매칭  | `point_radius:[2.355128 48.861118 16km]`                    |
| `bounding_box:`  | Standalone | 경계 상자 내 게시물을 매칭     | `bounding_box:[-105.301758 39.964069 -105.178505 40.09455]` |

***

## 게시물 유형 연산자

| Operator       | Type                 | Summary                    | Example                         |
| :------------- | :------------------- | :------------------------- | :------------------------------ |
| `is:retweet`   | Conjunction required | 리포스트를 매칭                   | `data @XDevelopers -is:retweet` |
| `is:reply`     | Conjunction required | 답글을 매칭                     | `from:XDevelopers is:reply`     |
| `is:quote`     | Conjunction required | 인용 게시물을 매칭                 | `"sentiment analysis" is:quote` |
| `is:verified`  | Conjunction required | 인증된 작성자의 게시물을 매칭           | `#nowplaying is:verified`       |
| `-is:nullcast` | Conjunction required | 프로모션 게시물을 제외(반드시 부정형으로 사용) | `"mobile games" -is:nullcast`   |

***

## 콘텐츠 유형 연산자

| Operator         | Type                 | Summary                        | Example                              |
| :--------------- | :------------------- | :----------------------------- | :----------------------------------- |
| `has:hashtags`   | Conjunction required | 해시태그가 포함된 게시물을 매칭              | `from:XDevelopers -has:hashtags`     |
| `has:cashtags`   | Conjunction required | 캐시태그가 포함된 게시물을 매칭              | `#stonks has:cashtags`               |
| `has:links`      | Conjunction required | 링크가 포함된 게시물을 매칭                | `from:XDevelopers has:links`         |
| `has:mentions`   | Conjunction required | 멘션이 포함된 게시물을 매칭                | `#nowplaying has:mentions`           |
| `has:media`      | Conjunction required | 미디어(사진, GIF, 동영상)가 포함된 게시물을 매칭 | `(kittens OR puppies) has:media`     |
| `has:images`     | Conjunction required | 이미지가 포함된 게시물을 매칭               | `#meme has:images`                   |
| `has:video_link` | Conjunction required | 네이티브 X 동영상이 포함된 게시물을 매칭        | `#icebucketchallenge has:video_link` |
| `has:geo`        | Conjunction required | 지오로케이션 데이터가 포함된 게시물을 매칭        | `recommend #paris has:geo`           |

***

## 샘플링 및 언어 연산자

| Operator  | Type                 | Summary               | Example                          |
| :-------- | :------------------- | :-------------------- | :------------------------------- |
| `sample:` | Conjunction required | 임의의 백분율 샘플(1-100)을 반환 | `#nowplaying @spotify sample:15` |
| `lang:`   | Conjunction required | 특정 언어로 분류된 게시물을 매칭    | `recommend #paris lang:en`       |

***

## 사용자 지표 연산자

| Operator           | Type | Summary                        | Example                       |
| :----------------- | :--- | :----------------------------- | :---------------------------- |
| `min_followers:`   | —    | 지정된 팔로워 수 이상을 가진 사용자의 게시물을 매칭  | `min_followers:1000`          |
| `followers_count:` | —    | 팔로워 수가 지정 범위에 속하는 사용자의 게시물을 매칭 | `followers_count:1000..10000` |
| `tweets_count:`    | —    | 게시물 수가 지정 범위에 속하는 사용자의 게시물을 매칭 | `tweets_count:1000..10000`    |
| `following_count:` | —    | 팔로잉 수가 지정 범위에 속하는 사용자의 게시물을 매칭 | `following_count:1000..10000` |
| `listed_count:`    | —    | 지정된 수의 리스트에 포함된 사용자의 게시물을 매칭   | `listed_count:10..100`        |

***

## 게시물 참조 연산자

| Operator                | Type | Summary                    | Example                                    |
| :---------------------- | :--- | :------------------------- | :----------------------------------------- |
| `in_reply_to_tweet_id:` | —    | 특정 게시물에 대한 답글을 매칭          | `in_reply_to_tweet_id:1539382664746020864` |
| `retweets_of_tweet_id:` | —    | 특정 게시물의 리포스트를 매칭           | `retweets_of_tweet_id:1539382664746020864` |
| `source:`               | —    | 특정 소스 애플리케이션에서 작성된 게시물을 매칭 | `source:"X for iPhone"`                    |

***

## 논리 연산자

| Operator    | Summary         | Example                    |
| :---------- | :-------------- | :------------------------- |
| `OR`        | 표현식 사이의 논리 OR   | `cat OR dog`               |
| Space (AND) | 표현식 사이의 논리 AND  | `cat dog` (둘 다 필요)         |
| `()`        | 복잡한 표현식을 위한 그룹화 | `(cat OR dog) -is:retweet` |
| `-`         | 부정/제외           | `cat -grumpy`              |

***

## 임베딩 연산자

<Note>
  **Enterprise 전용 — Embedding 티어 필요**

  `embedding:` 및 `embedding_threshold:` 연산자는 Filtered Stream에 대한 Embedding 티어 액세스가 프로비저닝된 Enterprise 계정에서만 사용할 수 있습니다. 지원되지 않는 티어에서는 규칙 생성이 "unavailable operator" 오류로 거부됩니다. 활성화하려면 담당 계정 담당자에게 문의하세요.
</Note>

이 연산자는 신경망 임베딩 모델을 사용하여 정확한 키워드 일치를 요구하는 대신 쿼리에 대한 *시맨틱 유사도*로 게시물을 매칭합니다.

| Operator                   | Type                 | Summary                                                       | Example                                                          |
| :------------------------- | :------------------- | :------------------------------------------------------------ | :--------------------------------------------------------------- |
| `embedding:"query"`        | Standalone           | 쿼리와 시맨틱적으로 유사한 게시물을 매칭합니다. 여러 단어로 된 쿼리는 따옴표로 묶어야 합니다.         | `embedding:"climate change policy"`                              |
| `embedding_threshold:X.XX` | Conjunction required | 매칭을 위한 최소 코사인 유사도(0.0–1.0). 기본값은 `0.3`. 0.3–0.6 사이의 값을 사용하세요. | `embedding:"cryptocurrency regulation" embedding_threshold:0.45` |

### 주요 요구 사항 및 참고 사항

* `embedding_threshold:`는 규칙 내에서 **단독으로** 사용할 수 없습니다. `embedding:`(또는 다른 독립형 연산자)과 함께 사용하세요.
* `embedding:`을 **부정하지 마세요**(예: `-embedding:"..."`는 지원되지 않음).
* 짧은 키워드보다 길고 설명적인 자연어 쿼리가 더 나은 결과를 제공합니다.
* 임베딩 쿼리 처리는 비동기적입니다 — 새로 생성한 규칙은 매칭을 시작하기까지 몇 초가 걸릴 수 있습니다.
* 게시물이 임베딩 규칙으로 매칭되면, 전달되는 페이로드의 `matching_rules` 항목에 `embedding_similarity` 및 `embedding_threshold`가 포함됩니다([Matching Posts to Rules](/x-api/posts/filtered-stream/integrate/matching-returned-tweets) 참조).

**예시 규칙:**

* `embedding:"electric vehicle announcements" lang:en -is:retweet has:links`
* `embedding:"natural disaster relief" embedding_threshold:0.45 has:media`
* `embedding:"renewable energy" embedding_threshold:0.4 OR embedding:"solar power investment"`

***

## 지원되는 언어

`lang:` 연산자는 다음 BCP 47 언어 코드를 지원합니다:

| Language | Code | Language | Code | Language | Code    |
| :------- | :--- | :------- | :--- | :------- | :------ |
| 암하라어     | `am` | 그리스어     | `el` | 포르투갈어    | `pt`    |
| 아랍어      | `ar` | 구자라트어    | `gu` | 루마니아어    | `ro`    |
| 아르메니아어   | `hy` | 히브리어     | `iw` | 러시아어     | `ru`    |
| 바스크어     | `eu` | 힌디어      | `hi` | 세르비아어    | `sr`    |
| 벵골어      | `bn` | 헝가리어     | `hu` | 중국어 간체   | `zh-CN` |
| 불가리아어    | `bg` | 인도네시아어   | `in` | 슬로바키아어   | `sk`    |
| 카탈로니아어   | `ca` | 이탈리아어    | `it` | 슬로베니아어   | `sl`    |
| 크로아티아어   | `hr` | 일본어      | `ja` | 스페인어     | `es`    |
| 체코어      | `cs` | 칸나다어     | `kn` | 스웨덴어     | `sv`    |
| 덴마크어     | `da` | 한국어      | `ko` | 타밀어      | `ta`    |
| 네덜란드어    | `nl` | 라트비아어    | `lv` | 텔루구어     | `te`    |
| 영어       | `en` | 리투아니아어   | `lt` | 태국어      | `th`    |
| 에스토니아어   | `et` | 말라얄람어    | `ml` | 중국어 번체   | `zh-TW` |
| 핀란드어     | `fi` | 마라티어     | `mr` | 터키어      | `tr`    |
| 프랑스어     | `fr` | 노르웨이어    | `no` | 우크라이나어   | `uk`    |
| 독일어      | `de` | 페르시아어    | `fa` | 우르두어     | `ur`    |
| 조지아어     | `ka` | 폴란드어     | `pl` | 베트남어     | `vi`    |

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="규칙 작성" icon="filter" href="/x-api/posts/filtered-stream/integrate/build-a-rule">
    규칙 구문과 모범 사례를 알아보세요
  </Card>

  <Card title="Filtered Stream 소개" icon="bolt" href="/x-api/posts/filtered-stream/introduction">
    Filtered Stream 시작하기
  </Card>

  <Card title="연결 끊김 처리" icon="plug" href="/x-api/fundamentals/handling-disconnections">
    스트리밍 연결 끊김을 처리하세요
  </Card>
</CardGroup>