> ## 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.

# クエリを作成する

> 演算子を使用して検索クエリを構築する方法を学びます

検索エンドポイントは、1 つのクエリを含む GET リクエストを受け取り、そのクエリに一致する過去の投稿の集合を返します。クエリは、さまざまなポストの属性に一致する演算子で構成されます。

***

<div id="query-limitations">
  ## クエリの制限
</div>

使用している[アクセスレベル](/ja/x-api/getting-started/about-x-api)に応じて、クエリには制限があります。

| アクセスレベル  | 最近の検索   | 全アーカイブ検索 |
| :------- | :------ | :------- |
| セルフサービス  | 512文字   | 1,024文字  |
| エンタープライズ | 4,096文字 | 4,096文字  |

***

<div id="operator-availability">
  ## オペレーターの利用可否
</div>

ほとんどのオペレーターはどの開発者でも利用できますが、一部は特定のアクセスレベルに限定されています。

* **コアオペレーター：** すべての[Project](/ja/resources/fundamentals/developer-apps)で利用可能
* **アドバンスドオペレーター：** 特定のアクセスレベルを持つ Project でのみ利用可能

利用可否の詳細については、[オペレーターの一覧](/ja/x-api/posts/search/integrate/operators)を参照してください。

***

<div id="operator-types-standalone-and-conjunction-required">
  ## 演算子の種類: 単独使用可能なものと結合が必要なもの
</div>

**単独演算子** は、それ単体で、または (結合が必要な演算子を含む) 他の任意の演算子と組み合わせて使用できます。

たとえば、このクエリが有効なのは、`#hashtag` が単独演算子だからです。

```
#xapiv2
```

**結合必須の演算子** は、クエリ内で単独では使用できません。少なくとも 1 つ以上の単独で使用可能な演算子と組み合わせて使用する必要があります。これは、これらの演算子だけを使用すると、非常に大量の投稿にマッチしてしまうためです。

たとえば、次のクエリは結合必須の演算子のみで構成されているため、**サポートされません**。

```
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>

**ダイアクリティカルマーク:** アクセントやダイアクリティカルマークを含む検索クエリは、それらのアクセントの有無にかかわらず投稿にマッチします。たとえば、`Diacrítica` は *Diacrítica* と *Diacritica* の両方にマッチします。

**大文字と小文字の区別:** すべてのオペレーターは大文字と小文字を区別しません。クエリ `cat` は *cat*、*CAT*、*Cat* にマッチします。

<Note>
  **Filtered stream の動作は異なります**

  [Filtered stream のルールを構築する](/ja/x-api/posts/filtered-stream/integrate/build-a-rule)場合、アクセント付きのキーワードは、同じくアクセントを含む投稿にのみマッチします。たとえば、`Diacrítica` は *Diacrítica* のみにマッチし、*Diacritica* にはマッチしません。
</Note>

***

<div id="quote-tweet-matching">
  ## 引用ツイートのマッチング
</div>

Search Posts を使用する場合、オペレーターは引用ツイートのコンテンツにはマッチしますが、引用された元のポストのコンテンツにはマッチしません。

<Note>
  [Filtered stream](/ja/x-api/posts/filtered-stream/introduction) は挙動が異なり、引用ツイートと元のポストの両方のコンテンツにマッチします。
</Note>

***

<div id="specificity-and-efficiency">
  ## 具体性と効率性
</div>

<Warning>
  単一のキーワードやハッシュタグといった広範なオペレーターの使用は推奨されません。膨大な数の投稿にマッチし、利用上限をすぐに消費してしまいます。
</Warning>

**効果的なクエリを構築するためのヒント:**

1. **最初は条件を絞り、あとから広げる** — 関連性の高い結果を返す、ターゲットを絞ったクエリを作成する
2. **複数のオペレーターを使う** — オペレーターを組み合わせて結果を絞り込む
3. **文字数を意識する** — クエリ文字列全体が上限にカウントされる

**進め方の例:**

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

# Better - adds language filter and exclusions
(happy OR happiness) lang:en -birthday -is:retweet

# さらに良い例 - 59文字でより具体的
(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">
  ### Step 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>

ハリケーン・ハービーに関する気象機関からの投稿をマッチさせます。

**クエリ:**

```
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:` 演算子を使用して、画像付きの日本語の、猫以外のペットに関する投稿を検索します。

まず、[Post lookup](/ja/x-api/posts/lookup/introduction) で `tweet.fields=context_annotations` を指定して、domain および entity の ID を特定します。

* Cats: `domain` 66, `entity` 852262932607926273
* Pets: `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="/ja/x-api/posts/search/integrate/operators">
    利用可能な演算子の一覧
  </Card>

  <Card title="検索クイックスタート" icon="rocket" href="/ja/x-api/posts/search/quickstart/recent-search">
    最初の検索リクエストを実行する
  </Card>

  <Card title="連携ガイド" icon="book" href="/ja/x-api/posts/search/integrate/overview">
    連携のための包括的なドキュメント
  </Card>
</CardGroup>