ネイティブクエリ

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

ネイティブクエリを使う理由

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

概要

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

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

どちらのメソッドも、クエリ対象のデータベースの connector ID が必要です。connector ID は Squid Console の connectors section で確認できます。

コアコンセプト

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

SQL データベースコネクタを使用している場合、executeNativeRelationalQuery メソッドを使って生の 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;
}

エラーハンドリング

Error	Cause	Solution
connector ID が無効	connector ID が、設定済みのデータベースコネクタのいずれにも一致しない	Squid Console の connectors section で connector ID を確認してください
SQL 構文エラー	生の SQL クエリに無効な構文が含まれている	まずデータベースに対して直接クエリをテストし、タイポや方言（dialect）固有の構文を確認してください
aggregation pipeline が無効	MongoDB pipeline に無効なステージやオペレーターが含まれている	MongoDB aggregation documentation を参照してください
セキュリティルールによる拒否	クエリが security rules によりブロックされた	ユーザーに権限があることを確認するか、backend の executable からネイティブクエリを実行してください

ベストプラクティス

パラメータ化クエリを使用して SQL injection を防いでください。文字列連結ではなく、parameters object 経由で値を渡します:

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}'`
);

機密性の高いネイティブクエリは、client から直接ではなく backend executables から実行し、クエリロジックと認証情報をサーバー側に置いてください。executables を参照してください。
ユースケースに対応している場合は、標準の query API を優先してください。ネイティブクエリは、Squid のクエリ抽象化、リアルタイム subscriptions、型安全性をバイパスします。
backend security rules でネイティブクエリを保護し、実行可能なクエリを制御してください。データアクセスの保護を参照してください。

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