メインコンテンツまでスキップ

Elasticsearch

Squid は Elasticsearch cluster に接続し、Squid application の data source として使用できます。​

Elasticsearch connector を使用すると、Squid Client SDK を通じて index に query を実行し、native Elasticsearch query を実行し、AI agent が data を使用して質問に回答できるようにします。

注記

Elasticsearch connector は read-only です。search、count、aggregation、その他の read operation はサポートされます。document write、_bulk、_update_by_query、_delete_by_query は拒否されます。

Elasticsearch 側の前提条件​

  • https://your-elasticsearch-host:9200 など、scheme と port を含む到達可能な node URL。
  • optional で、公開する index に対する read privilege を持つ user。connector は HTTP basic auth（username + password）で authenticate します。省略した場合は unauthenticated で接続します。
  • private network 上の cluster では、machine 上で実行され Squid が local resource に access できるようにする proxy、Squidlet を通じて connection を route できます。

Elasticsearch Connector の追加​

  1. Squid Console を開き、Elasticsearch で使用する application を選択します。
  2. Connectors tab をクリックし、Available connectors をクリックします。
  3. Elasticsearch connector を選択します。
  4. 次の configuration information を入力します。
  • Connector ID - 簡潔で connector の識別に役立つ ID を選択します。
  • Database Endpoint - cluster URL。例: https://your-elasticsearch-host:9200。
  • Database Username - Optional。read access を持つ user。
  • Database Password - Optional。password を private に保つには、Squid Secrets に保存します。
  • Squidlet ID - Optional。private cluster に到達するための Squidlet proxy の ID。
  • Tables to Process - Optional。schema discovery に含める index の comma-separated list。regex pattern を指定するには forward slash を使用します（例: /^logs-.*/）。

Index の Discovery​

connector を追加した後、Schema tab を使用して index と data stream を discover します。Squid は各 index の mapping を読み取り schema を構築し、numbered index series（time-based index など）を glob pattern に collapse します。system index は除外されます。

Data の Query​

connector ID を渡して、他の Squid collection と同様に Client SDK から index に query を実行します。

Client code
const articles = await squid
  .collection<Article>('articles', 'YOUR_ELASTICSEARCH_CONNECTOR_ID')
  .query()
  .like('title', '%observability%')
  .snapshot();

Elasticsearch query DSL への full access が必要な場合は、index、request body、必要に応じて endpoint と HTTP method（default は _search と GET）を渡して、executeNativeElasticQuery による native query を実行します。

Client code
const result = await squid.executeNativeElasticQuery(
  'YOUR_ELASTICSEARCH_CONNECTOR_ID',
  'articles',
  {
    query: { match: { title: 'observability' } },
    size: 10,
  },
);

native query は、_search、_count、_msearch、_mget、_mapping、_sql、_eql などの read-only endpoint に制限されます。mutation endpoint への request は error を返します。

注意すべき Elasticsearch 固有の behavior:

  • limit が設定されていない場合、standard query は最大 1000 result を返します。
  • 独自の timeout を指定しない search request には、30 秒の server-side timeout が設定されます。そのため runaway query は cluster により cancel されます。
  • connector ごとに最大 15 の concurrent native query が許可されます。これを超える request は queue に追加されず、拒否されます。

Database の保護​

default では security rule が必要です。production environment では、security rule なしで connector への access を許可しないことが不可欠です。database data の保護に関する詳細は、security rules documentationを参照してください。

Squid で data を操作する方法については、Client SDK documentationを参照してください。