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

ネイティブクエリ

raw SQL やその他のデータベース固有のクエリを、データベースに対して直接実行します。​

ネイティブクエリを使用する理由​

Squid Client SDK には強力なクエリ機能がありますが、一部の操作では標準の query API では利用できないデータベース固有の機能が必要になります。たとえば、SQL のサブセレクト、複雑な集計、ストアドプロシージャ、または MongoDB の aggregation pipeline などです。ネイティブクエリを使うと、こうした高度な機能が必要な場合に、データベースコネクタに対して raw クエリを直接実行できます。

概要​

ネイティブクエリは Squid のクエリ抽象化をバイパスし、データベースに対して直接実行します。Squid は 2 種類のネイティブクエリをサポートします。

  • リレーショナルクエリ：SQL データベース（PostgreSQL, MySQL, ClickHouse, MS SQL Server）向け。executeNativeRelationalQuery を使用
  • MongoDB クエリ：MongoDB コネクタ向け。executeNativeMongoQuery を使用

どちらのメソッドも、クエリしたいデータベースの connector ID が必要です。connector ID は Squid Console の connectors セクション で確認できます。

コアコンセプト​

ネイティブリレーショナルクエリ​

SQL データベースコネクタを使用している場合、executeNativeRelationalQuery メソッドで raw SQL を実行できます。データベースの connector ID と SQL クエリを渡します。

次の例は、パラメータ化された値でネイティブ SQL クエリを実行します。

Client code
async function runNativeQuery(queryParam: string): Promise<any> {
  const response = await this.squid.executeNativeRelationalQuery(
    'DATABASE_CONNECTOR_ID',
    'SELECT * FROM SQUIDS WHERE YEAR = ${year}',
    { year: queryParam }
  );
  return response;
}

ネイティブクエリを安全にするには、Squid backend の Squid Service function を使用してください。詳しくは、データアクセスの保護に関するドキュメント を参照してください。

ネイティブ MongoDB クエリ​

executeNativeMongoQuery メソッドは、指定されたパラメータでネイティブの MongoDB aggregation pipeline を実行し、結果を含む promise を返します。

次の例は、Mongo aggregation pipeline を実行します。

Client code
async function countDocuments(): Promise<any> {
  const response = await this.squid.executeNativeMongoQuery(
    'DATABASE_CONNECTOR_ID',
    'COLLECTION_NAME',
    [{ $count: 'totalApplications' }]
  );
  return response;
}

エラーハンドリング​

ErrorCauseSolution
Invalid connector IDconnector ID が、設定済みのデータベースコネクタのいずれにも一致しないSquid Console の connectors セクション で connector ID を確認する
SQL syntax errorraw SQL クエリに無効な構文が含まれているまずデータベースに対して直接クエリをテストする。タイプミスや方言（dialect）固有の構文を確認する
Invalid aggregation pipelineMongoDB pipeline に無効な stage または operator が含まれているMongoDB aggregation のドキュメント を参照する
Security rule rejectionクエリが security rules によりブロックされたユーザーに権限があることを確認する、または backend の executable からネイティブクエリを実行する

ベストプラクティス​

  1. パラメータ化クエリを使用して SQL injection を防ぎます。文字列連結ではなく parameters オブジェクト経由で値を渡します。

    Client code
    // Recommended: parameterized query
    const response = await this.squid.executeNativeRelationalQuery(
      'CONNECTOR_ID',
      'SELECT * FROM users WHERE name = ${name}',
      { name: userInput }
    );

    // Avoid: string concatenation (vulnerable to injection)
    const response = await this.squid.executeNativeRelationalQuery(
      'CONNECTOR_ID',
      `SELECT * FROM users WHERE name = '${userInput}'`
    );

  2. クライアントから直接ではなく backend executables から機密性の高いネイティブクエリを実行して、クエリロジックと認証情報をサーバー側に保持します。executables を参照してください。

  3. ユースケースを満たせる場合は 標準の query API を優先します。ネイティブクエリは Squid のクエリ抽象化、リアルタイムサブスクリプション、型安全性をバイパスします。

  4. backend security rules でネイティブクエリを保護し、実行可能なクエリを制御します。データアクセスの保護 を参照してください。