NEAREST BY 句

適用対象:はい Databricks Runtime 18.3 以降とマークされているチェック

カスタム距離または類似性式の上位 k ランク付けで JOIN を拡張します。クエリ (左) table_referenceの各行について、ranking_expressionに基づいてターゲット (右) テーブルから一致する行の上位num_resultsを検索し、連結された行として返します。

ranking_expressionには、2 つのテーブルの 2 つの行のペア (vector_cosine_similarity、vector_l2_distance、vector_inner_product 、複数の関数を組み合わせた複合式など) をスコア付けする任意の順序付け可能なスカラー式を指定できます。

Syntax

{ INNER | LEFT [ OUTER ] } JOIN target_table_reference
  { APPROX | EXACT } NEAREST [ num_results ]
  BY { DISTANCE | SIMILARITY } ranking_expression

Parameters

target_table_reference

検索するターゲットテーブル。テーブル、サブクエリ、または CTE を指定できます。
{ INNER | LEFT [ OUTER ] }

オプション。結合の種類。既定値は INNER です。
- INNER は、一致する候補がないクエリ行を削除します。
- LEFT OUTER は、すべてのクエリ行を返します。ターゲット側の列は、候補が存在しない場合 (たとえば、ターゲットテーブルが空であるか、すべての候補がNULLされている場合) にNULLされます。クエリ行の候補が num_results 未満の場合は、使用可能な候補のみが返されます。
その他の結合の種類 (RIGHT、 FULL、 SEMI、 ANTI、 CROSS、 NATURAL) では、 NEAREST_BY_JOIN.UNSUPPORTED_JOIN_TYPEが発生します。
{ APPROX | EXACT }

結果セットコントラクトを制御します。
- EXACT は、 ranking_expressionの下の正確な top-k 行を返します。
- APPROX は、正確なランク付けに近い top-k セットを返します。オプティマイザーでは、すべての候補を評価する代わりに、より高速で近似的な検索戦略を使用できます。
NEAREST [ num_results ]

省略可能な正の整数リテラル。既定値は 1 です。 [1, 100000]範囲内にある必要があります。ターゲットテーブルの一致する行数が num_resultsよりも少ない場合は、使用可能な行のみが返されます。

範囲外の値は NEAREST_BY_JOIN.NUM_RESULTS_OUT_OF_RANGE発生します。
距離別 |類似

ranking_expressionの順序を設定します。
- DISTANCE は、行を最も小さい値 (最も近い = 最も低い距離) でランク付けします。
- SIMILARITY は、最も大きい値 (最も近い = 最も類似性が高い) で行をランク付けします。
ranking_expression

両方のテーブルの列を参照できるスカラー式。

一般的な選択肢は次のとおりです。
- vector_cosine_similarityや vector_inner_productなどの類似性関数
- vector_l2_distanceのような距離関数、
- マンハッタン距離のような数値の距離: vector_norm(zip_with(a.col, b.col, (x, y) -> x - y), 1.0f)。
MAP など、この式が順序付けをサポートしていないデータ型を返す場合、Azure Databricksは DATATYPE_MISMATCH を発生させます。INVALID_ORDERING_TYPE。

注記

非対称性

NEAREST BY は可換ではありません。クエリ側は結果を固定します。各クエリ行は最大 num_results 出力行を生成します。

テーブルから 100 行が結合users、テーブルから 1,000 行がNEAREST 5products場合、結合は最大 500 行を返します。
結合の両側を切り替えてusersproducts結合すると、最大 5,000 行が返されます。

2 つの側をスワップすると異なる質問が発生するため、 INNER JOINでも結果が異なります。

ストリーミング

NEAREST BY は、ストリーミングデータフレームまたはデータセットではサポートされていません。ストリーミングソースに対するクエリでは、 NEAREST_BY_JOIN.STREAMING_NOT_SUPPORTEDが発生します。

入力の埋め込み

ベクタースコアリング関数を使用する場合、両方のベクター引数が同じ次元で ARRAY<FLOAT> する必要があります。型およびNULL処理ルールについては、vector_cosine_similarity関数を参照してください。

文字列値から埋め込みを計算するには、 databricks でホストされる埋め込みモデル ( databricks-gte-large-en など) でai_queryを使用します。

一般的なエラー状態

DATATYPE_MISMATCH。INVALID_ORDERING_TYPE
NEAREST_BY_JOIN.NUM_RESULTS_OUT_OF_RANGE
NEAREST_BY_JOIN.STREAMING_NOT_SUPPORTED
NEAREST_BY_JOIN.UNSUPPORTED_JOIN_TYPE

例示

次の例では、これらのテーブルを使用します。埋め込みは簡潔にするために3次元ベクトルとして示されています。実際には、それらはより高次元であり、埋め込みモデルによって計算されます。

> CREATE TEMP VIEW users(user_id, name, embedding) AS
    VALUES
      (1, 'Alice', ARRAY(1.0f, 0.0f, 0.0f)),
      (2, 'Bob',   ARRAY(0.0f, 1.0f, 0.0f)),
      (3, 'Carol', ARRAY(0.0f, 0.0f, 0.0f));

> CREATE TEMP VIEW products(product_id, name, price, country, embedding) AS
    VALUES
      ('P1', 'Trail running shoes', 120, 'EU', ARRAY(0.9f, 0.1f, 0.1f)),
      ('P2', 'Hiking boots',        180, 'EU', ARRAY(0.8f, 0.2f, 0.0f)),
      ('P3', 'Office shoes',         95, 'US', ARRAY(0.1f, 0.9f, 0.1f)),
      ('P4', 'Sandals',              45, 'US', ARRAY(0.0f, 0.8f, 0.2f)),
      ('P5', 'Running shoes',       110, 'EU', ARRAY(0.5f, 0.5f, 0.0f));

-- Ad-hoc vector search with an explicit query vector.
> SELECT t.product_id, t.name
    FROM (SELECT ARRAY(1.0f, 0.0f, 0.0f) AS embedding) q
    INNER JOIN products t
      APPROX NEAREST 3 BY SIMILARITY vector_cosine_similarity(q.embedding, t.embedding);
 product_id  name
 ----------  -------------------
 P1          Trail running shoes
 P2          Hiking boots
 P5          Running shoes

-- Batch recommendations: for every user, return the 2 nearest products.
> SELECT q.user_id, q.name, t.product_id, t.name AS product
    FROM users q
    INNER JOIN products t
      APPROX NEAREST 2 BY SIMILARITY vector_cosine_similarity(q.embedding, t.embedding);
 user_id  name   product_id  product
 -------  -----  ----------  -------------------
 1        Alice  P1          Trail running shoes
 1        Alice  P2          Hiking boots
 2        Bob    P3          Office shoes
 2        Bob    P4          Sandals

-- Pre-filter the target table via a subquery (EU products only).
> SELECT q.user_id, q.name, t.product_id, t.name AS product, t.price
    FROM users q
    INNER JOIN (SELECT * FROM products WHERE country = 'EU') AS t
      APPROX NEAREST 2 BY SIMILARITY vector_cosine_similarity(q.embedding, t.embedding);
 user_id  name   product_id  product              price
 -------  -----  ----------  -------------------  -----
 1        Alice  P1          Trail running shoes  120
 1        Alice  P2          Hiking boots         180
 2        Bob    P5          Running shoes        110
 2        Bob    P2          Hiking boots         180

-- LEFT OUTER returns every query row. Carol's embedding has zero magnitude,
-- so vector_cosine_similarity returns NULL for all comparisons and her row
-- is preserved with NULL target columns.
> SELECT q.user_id, q.name, t.product_id, t.name AS product
    FROM users q
    LEFT OUTER JOIN products t
      APPROX NEAREST 2 BY SIMILARITY vector_cosine_similarity(q.embedding, t.embedding);
 user_id  name   product_id  product
 -------  -----  ----------  -------------------
 1        Alice  P1          Trail running shoes
 1        Alice  P2          Hiking boots
 2        Bob    P3          Office shoes
 2        Bob    P4          Sandals
 3        Carol  NULL        NULL

-- EXACT returns the exact top-k under the ranking expression.
> SELECT t.product_id, t.name
    FROM (SELECT ARRAY(1.0f, 0.0f, 0.0f) AS embedding) q
    INNER JOIN products t
      EXACT NEAREST 3 BY DISTANCE vector_l2_distance(q.embedding, t.embedding);
 product_id  name
 ----------  -------------------
 P1          Trail running shoes
 P2          Hiking boots
 P5          Running shoes

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-06-01