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

# 쿼리 작성

> 연산자를 사용해 검색 쿼리를 작성하는 방법을 알아봅니다

검색 엔드포인트는 GET 요청으로 단일 쿼리를 받아 해당 쿼리와 일치하는 과거 포스트 집합을 반환합니다. 쿼리는 다양한 포스트 속성에 매칭되는 연산자들로 구성됩니다.

***

<div id="query-limitations">
  ## 쿼리 제한
</div>

사용 중인 [액세스 수준](/ko/x-api/getting-started/about-x-api)에 따라 쿼리 길이에 다음과 같은 제한이 적용됩니다:

| 액세스 수준 | 최근 검색  | 전체 아카이브 검색 |
| :----- | :----- | :--------- |
| 셀프 서비스 | 512자   | 1,024자     |
| 엔터프라이즈 | 4,096자 | 4,096자     |

***

<div id="operator-availability">
  ## 연산자 사용 가능 여부
</div>

대부분의 연산자는 모든 개발자가 사용할 수 있지만, 일부는 특정 액세스 수준에서만 사용할 수 있습니다.

* **핵심 연산자:** 모든 [Project](/ko/resources/fundamentals/developer-apps)에서 사용할 수 있습니다.
* **고급 연산자:** 특정 액세스 수준이 부여된 Project에서만 사용할 수 있습니다.

사용 가능 여부에 대한 자세한 내용은 전체 [연산자 목록](/ko/x-api/posts/search/integrate/operators)을 참고하세요.

***

<div id="operator-types-standalone-and-conjunction-required">
  ## 연산자 유형: 단독 사용 가능 및 결합 필요
</div>

**단독 연산자**는 단독으로도 사용할 수 있고, (결합이 필요한 연산자를 포함해) 다른 어떤 연산자와도 함께 사용할 수 있습니다.

예를 들어, 이 쿼리는 `#hashtag`가 단독 연산자이기 때문에 유효합니다.

```
#xapiv2
```

**연접 필수 연산자**는 쿼리에서 단독으로 사용할 수 없으며, 하나 이상의 단독 사용 가능 연산자가 포함될 때에만 사용할 수 있습니다. 이는 이러한 연산자만 사용할 경우, 포스트가 지나치게 많이 매칭되기 때문입니다.

예를 들어, 다음 쿼리들은 연접 필수 연산자만 포함하고 있으므로 **지원되지 않습니다**:

```
has:media
```

```
has:links OR is:retweet
```

`"X data"`와 같은 구문을 단독 연산자로 추가하면 쿼리가 올바르게 동작합니다.

```
"X data" has:mentions (has:media OR has:links)
```

***

<div id="boolean-operators-and-grouping">
  ## 불리언 연산자와 그룹화
</div>

여러 연산자를 다음 도구를 사용해 함께 연결할 수 있습니다:

| Operator                   | Description                 | Example                                                                    |
| :------------------------- | :-------------------------- | :------------------------------------------------------------------------- |
| **AND** (space)            | 포스트는 두 조건을 모두 만족해야 합니다      | `snow day #NoSchool`은 "snow" AND "day" AND #NoSchool을 모두 포함하는 포스트와 일치합니다   |
| **OR**                     | 포스트는 두 조건 중 하나 이상을 만족하면 됩니다 | `grumpy OR cat OR #meme`은 "grumpy" OR "cat" OR #meme 중 하나를 포함하는 포스트와 일치합니다 |
| **NOT** (dash)             | 이 조건과 일치하는 포스트를 제외합니다       | `cat #meme -grumpy`는 "cat"과 #meme은 포함하지만 "grumpy"는 포함하지 않는 포스트와 일치합니다      |
| **Grouping** (parentheses) | 연산자들을 괄호로 묶어 그룹화합니다         | `(grumpy cat) OR (#meme has:images)`는 두 그룹 중 하나와 일치합니다                     |

<Note>
  **부정에 대한 참고 사항**

  * 연산자 `-is:nullcast`는 항상 부정 연산자로만 사용해야 합니다
  * 부정 연산자는 단독으로 사용할 수 없습니다
  * 그룹화된 연산자를 부정하지 마십시오. `skiing -(snow OR day OR noschool)` 대신 `skiing -snow -day -noschool`을 사용하세요
</Note>

***

<div id="order-of-operations">
  ## 연산 순서
</div>

AND와 OR를 함께 사용할 때:

1. AND 논리로 연결된 연산자가 먼저 평가됩니다
2. 그다음 OR 논리로 연결된 연산자가 적용됩니다

**예시:**

| Query                    | Evaluated as               |
| :----------------------- | :------------------------- |
| `apple OR iphone ipad`   | `apple OR (iphone ipad)`   |
| `ipad iphone OR android` | `(iphone ipad) OR android` |

모호성을 없애려면 괄호를 사용하세요:

```
(apple OR iphone) ipad
```

```
iphone (ipad OR android)
```

***

<div id="punctuation-diacritics-and-case-sensitivity">
  ## 구두점, 발음 구별 기호, 대소문자 구분
</div>

**발음 구별 기호(Diacritics):** 악센트나 발음 구별 기호가 포함된 검색어는 해당 기호가 있는 포스트와 없는 포스트 모두에 일치합니다. 예를 들어, `Diacrítica`는 \_Diacrítica\_와 *Diacritica* 모두에 일치합니다.

**대소문자 구분:** 모든 연산자는 대소문자를 구분하지 않습니다. 예를 들어, `cat` 쿼리는 *cat*, *CAT*, *Cat* 모두에 일치합니다.

<Note>
  **Filtered stream은 다르게 동작합니다**

  [Filtered stream 규칙을 작성할 때](/ko/x-api/posts/filtered-stream/integrate/build-a-rule), 악센트가 있는 키워드는 악센트가 포함된 포스트에만 일치합니다. 예를 들어, `Diacrítica`는 \_Diacrítica\_에만 일치하고 \_Diacritica\_에는 일치하지 않습니다.
</Note>

***

<div id="quote-tweet-matching">
  ## Quote Tweet 일치
</div>

Search Posts를 사용할 때 연산자는 Quote Tweet의 내용과는 일치하지만, 인용된 원본 게시물의 내용과는 **일치하지 않습니다**.

<Note>
  [Filtered stream](/ko/x-api/posts/filtered-stream/introduction)은 동작이 다릅니다. Quote Tweet과 원본 게시물의 내용 모두와 일치합니다.
</Note>

***

<div id="specificity-and-efficiency">
  ## 구체성과 효율성
</div>

<Warning>
  단일 키워드나 해시태그와 같은 광범위한 연산자만 사용하는 것은 권장되지 않습니다. 방대한 양의 포스트와 일치하여 사용 한도를 빠르게 소진하게 됩니다.
</Warning>

**효과적인 쿼리를 구성하기 위한 팁:**

1. **처음에는 구체적으로 시작한 뒤, 점차 범위를 넓히세요** — 관련성이 높은 결과를 반환하는 타깃 쿼리를 만드세요
2. **여러 연산자를 사용하세요** — 연산자를 조합해 결과를 좁히세요
3. **문자 수를 주의하세요** — 전체 쿼리 문자열이 제한에 포함됩니다

**예시 발전 단계:**

```
# Too broad - 200,000+ Posts per day
happy

# 개선됨 - 언어 필터 및 제외 조건 추가
(happy OR happiness) lang:en -birthday -is:retweet

# Even better - 59 characters, more specific
(happy OR happiness) place_country:GB -birthday -is:retweet
```

***

<div id="iteratively-building-a-query">
  ## 쿼리를 단계적으로 구성하기
</div>

<div id="step-1-start-with-a-basic-query">
  ### 1단계: 기본 쿼리부터 시작하기
</div>

```
happy OR happiness
```

<div id="step-2-test-and-narrow-based-on-results">
  ### 2단계: 결과를 기준으로 테스트하고 범위를 좁히기
</div>

여러 언어로 작성된 포스트가 많다는 것을 확인했습니다. 언어 필터를 추가하세요:

```
(happy OR happiness) lang:en
```

생일 축하 메시지가 검색되고 있습니다. 이런 메시지와 리트윗은 제외해 보겠습니다:

```
(happy OR happiness) lang:en -birthday -is:retweet
```

<div id="step-3-broaden-for-better-coverage">
  ### 3단계: 범위를 넓혀 커버리지를 높이기
</div>

더 많은 감정을 포착할 수 있도록 관련 키워드를 추가하세요:

```
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet
```

<div id="step-4-adjust-for-trends">
  ### 4단계: 트렌드에 맞게 조정
</div>

휴일 포스트가 결과에 나타납니다. 제외하세요:

```
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays
```

***

<div id="adding-a-query-to-your-request">
  ## 요청에 쿼리 추가하기
</div>

`query` 매개변수를 사용하고, 쿼리를 HTTP로 인코딩하세요:

```bash theme={null}
curl "https://api.x.com/2/tweets/search/recent?\
query=cat%20has%3Amedia%20-grumpy&\
tweet.fields=created_at&\
max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

***

<div id="query-examples">
  ## 쿼리 예제
</div>

<div id="tracking-a-natural-disaster">
  ### 자연재해 추적
</div>

허리케인 Harvey에 대한 기상 기관의 포스트를 매칭합니다:

**쿼리:**

```
has:geo (from:NWSNHC OR from:NHC_Atlantic OR from:NWSHouston OR from:NWSSanAntonio OR from:USGS_TexasRain OR from:USGS_TexasFlood OR from:JeffLindner1) -is:retweet
```

**전체 요청 URL:**

```
https://api.x.com/2/tweets/search/recent?query=has%3Ageo%20(from%3ANWSNHC%20OR%20from%3ANHC_Atlantic%20OR%20from%3ANWSHouston%20OR%20from%3ANWSSanAntonio%20OR%20from%3AUSGS_TexasRain%20OR%20from%3AUSGS_TexasFlood%20OR%20from%3AJeffLindner1)%20-is%3Aretweet
```

<div id="sentiment-analysis-for-nowplaying">
  ### #nowplaying에 대한 감성 분석
</div>

**긍정 감성:**

```
#nowplaying (happy OR exciting OR excited OR favorite OR fav OR amazing OR lovely OR incredible) (place_country:US OR place_country:MX OR place_country:CA) -horrible -worst -sucks -bad -disappointing
```

**부정 감성:**

```
#nowplaying (horrible OR worst OR sucks OR bad OR disappointing) (place_country:US OR place_country:MX OR place_country:CA) -happy -exciting -excited -favorite -fav -amazing -lovely -incredible
```

<div id="using-post-annotations">
  ### 게시물 주석 활용
</div>

`context:` 연산자를 사용하여 반려동물(고양이 제외)에 대한 일본어 포스트 중 이미지가 포함된 포스트를 찾습니다:

먼저 [게시물 조회](/ko/x-api/posts/lookup/introduction)를 사용하고 `tweet.fields=context_annotations`를 지정하여 domain.entity ID를 확인합니다:

* 고양이: `domain` 66, `entity` 852262932607926273
* 반려동물: `domain` 65, `entity` 852262932607926273

**쿼리:**

```
context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja
```

***

<div id="tools">
  ## 도구
</div>

<Card title="쿼리 빌더 도구" icon="wrench" href="https://developer.x.com/apitools/query?query=">
  인터랙티브하게 쿼리를 작성하고 테스트해 보세요
</Card>

***

<div id="next-steps">
  ## 다음 단계
</div>

<CardGroup cols={2}>
  <Card title="연산자 참조" icon="list" href="/ko/x-api/posts/search/integrate/operators">
    모든 사용 가능한 연산자 목록
  </Card>

  <Card title="검색 빠른 시작" icon="rocket" href="/ko/x-api/posts/search/quickstart/recent-search">
    첫 검색 요청 보내기
  </Card>

  <Card title="연동 가이드" icon="book" href="/ko/x-api/posts/search/integrate/overview">
    전체 연동 문서
  </Card>
</CardGroup>