在 Azure Data Factory 和 Azure Synapse Analytics 中的查詢活動

適用於： Azure Data Factory Azure Synapse Analytics

查閱活動可以從資料處理站和 Synapse 管道所支援的任何資料來源擷取資料集。 您可以將其用來動態判斷在後續活動中要處理哪些物件，而不是將物件名稱寫入程式碼。 某些物件範例是檔案和資料表。

查閱活動會讀取並傳回組態檔或資料表的內容。 也會傳回執行查詢或預存程序的結果。 輸出可以是單一值或屬性陣列，可以在後續的複製、轉換或控制流程活動中取用，例如 ForEach 活動。

使用 UI 建立查詢活動

若要在管道中使用查詢活動，請執行下列步驟：

1. 在管線活動窗格中搜尋查閱，並將查閱活動拖曳到管線畫布。

2. 在畫布上選取新的查詢活動（如果尚未選取），然後點選其 [設定] 索引標籤以編輯詳細資料。

   

3. 選擇現有的來源資料集，或選取 [新增] 按鈕以建立新的資料集。

4. 從來源資料集識別要包含資料列的選項會根據資料集類型而有所不同。 上述範例顯示分隔符號文字資料集的設定選項。 以下是 Azure SQL 資料表資料集與 OData 資料集的設定選項範例。

   

   

支援的功能

請注意以下要點：

• 查閱活動最多可傳回 5,000 個資料列；如果結果集包含更多記錄，則會傳回前 5,000 個資料列。
• 查閱活動輸出最多支援 4 MB 的大小，如果大小超過限制，活動將會失敗。
• 逾時之前的查閱活動持續時間最長為 24小時。

查詢活動支援下列資料來源。

語法

{
    "name":"LookupActivity",
    "type":"Lookup",
    "typeProperties":{
        "source":{
            "type":"<source type>"
        },
        "dataset":{
            "referenceName":"<source dataset name>",
            "type":"DatasetReference"
        },
        "firstRowOnly":<true or false>
    }
}

類型屬性

使用查閱活動結果

查閱結果會在活動執行結果的 output 區段中傳回。

• 當 firstRowOnly 設為 true (預設值)，輸出格式如下列程式碼所示。 查詢結果位於固定的 firstRow 鍵底下。 若要在後續活動中使用結果，請使用 @{activity('LookupActivity').output.firstRow.table} 模式。

  {
      "firstRow":
      {
          "Id": "1",
          "schema":"dbo",
          "table":"Table1"
      }
  }
  

• 當 firstRowOnly 設為 false，輸出格式如下列程式碼所示。 count 欄位會指出傳回多少筆記錄。 詳細的值會顯示在固定 value 陣列下。 在這種情況下，查閱活動後面接著 ForEach 活動。 您可以使用 value 模式，將 items 陣列傳遞至 ForEach 活動的 @activity('MyLookupActivity').output.value 欄位。 若要存取 value 陣列中的元素，請使用下列語法：@{activity('lookupActivity').output.value[zero based index].propertyname}。 例如 @{activity('lookupActivity').output.value[0].schema}。

  {
      "count": "2",
      "value": [
          {
              "Id": "1",
              "schema":"dbo",
              "table":"Table1"
          },
          {
              "Id": "2",
              "schema":"dbo",
              "table":"Table2"
          }
      ]
  } 
  

範例

在此範例中，管道包含兩個活動：查閱和複製。 複製活動是將資料從 Azure SQL Database 實例中的 SQL 資料表複製到 Azure Blob 儲存。 SQL 資料表的名稱會儲存在 Blob 儲存體的 JSON 檔案中。 查詢活動會在執行階段查詢資料表名稱。 使用這種方法可動態修改 JSON。 您不需要重新部署管線或資料集。

此例子僅示範查找第一列資料。 若要查閱所有資料列並鏈結結果與 ForEach 活動，請參閱大量複製多個資料表中的範例。

管線

• 查詢活動設定為使用 LookupDataset，指的是 Azure Blob 儲存中的一個位置。 查閱活動會從這個位置的 JSON 檔案讀取 SQL 資料表的名稱。
• 複製活動會使用查詢活動的結果，即 SQL 資料表的名稱。 SourceDataset 中的 tableName 屬性會設定為使用查閱活動的輸出。 複製活動是將資料從 SQL 資料表複製到 Azure Blob 儲存中的某個位置。 此位置會由 SinkDataset 屬性指定。

{
    "name": "LookupPipelineDemo",
    "properties": {
        "activities": [
            {
                "name": "LookupActivity",
                "type": "Lookup",
                "dependsOn": [],
                "policy": {
                    "timeout": "7.00:00:00",
                    "retry": 0,
                    "retryIntervalInSeconds": 30,
                    "secureOutput": false,
                    "secureInput": false
                },
                "userProperties": [],
                "typeProperties": {
                    "source": {
                        "type": "JsonSource",
                        "storeSettings": {
                            "type": "AzureBlobStorageReadSettings",
                            "recursive": true
                        },
                        "formatSettings": {
                            "type": "JsonReadSettings"
                        }
                    },
                    "dataset": {
                        "referenceName": "LookupDataset",
                        "type": "DatasetReference"
                    },
                    "firstRowOnly": true
                }
            },
            {
                "name": "CopyActivity",
                "type": "Copy",
                "dependsOn": [
                    {
                        "activity": "LookupActivity",
                        "dependencyConditions": [
                            "Succeeded"
                        ]
                    }
                ],
                "policy": {
                    "timeout": "7.00:00:00",
                    "retry": 0,
                    "retryIntervalInSeconds": 30,
                    "secureOutput": false,
                    "secureInput": false
                },
                "userProperties": [],
                "typeProperties": {
                    "source": {
                        "type": "AzureSqlSource",
                        "sqlReaderQuery": {
                            "value": "select * from [@{activity('LookupActivity').output.firstRow.schema}].[@{activity('LookupActivity').output.firstRow.table}]",
                            "type": "Expression"
                        },
                        "queryTimeout": "02:00:00",
                        "partitionOption": "None"
                    },
                    "sink": {
                        "type": "DelimitedTextSink",
                        "storeSettings": {
                            "type": "AzureBlobStorageWriteSettings"
                        },
                        "formatSettings": {
                            "type": "DelimitedTextWriteSettings",
                            "quoteAllText": true,
                            "fileExtension": ".txt"
                        }
                    },
                    "enableStaging": false,
                    "translator": {
                        "type": "TabularTranslator",
                        "typeConversion": true,
                        "typeConversionSettings": {
                            "allowDataTruncation": true,
                            "treatBooleanAsNumber": false
                        }
                    }
                },
                "inputs": [
                    {
                        "referenceName": "SourceDataset",
                        "type": "DatasetReference",
                        "parameters": {
                            "schemaName": {
                                "value": "@activity('LookupActivity').output.firstRow.schema",
                                "type": "Expression"
                            },
                            "tableName": {
                                "value": "@activity('LookupActivity').output.firstRow.table",
                                "type": "Expression"
                            }
                        }
                    }
                ],
                "outputs": [
                    {
                        "referenceName": "SinkDataset",
                        "type": "DatasetReference",
                        "parameters": {
                            "schema": {
                                "value": "@activity('LookupActivity').output.firstRow.schema",
                                "type": "Expression"
                            },
                            "table": {
                                "value": "@activity('LookupActivity').output.firstRow.table",
                                "type": "Expression"
                            }
                        }
                    }
                ]
            }
        ],
        "annotations": [],
        "lastPublishTime": "2020-08-17T10:48:25Z"
    }
}

查閱資料集

lookup 資料集是 AzureBlobStorageLinkedService 類型指定的 Azure 儲存體 查找資料夾中的 sourcetable.json 檔案。

{
    "name": "LookupDataset",
    "properties": {
        "linkedServiceName": {
            "referenceName": "AzureBlobStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "annotations": [],
        "type": "Json",
        "typeProperties": {
            "location": {
                "type": "AzureBlobStorageLocation",
                "fileName": "sourcetable.json",
                "container": "lookup"
            }
        }
    }
}

複製活動的來源資料集

來源資料集使用查閱活動的輸出，也就是 SQL 資料表的名稱。 複製活動會將資料從這個 SQL 資料表複製到 Azure Blob 儲存的某個位置。 此位置會由匯入資料集指定。

{
    "name": "SourceDataset",
    "properties": {
        "linkedServiceName": {
            "referenceName": "AzureSqlDatabase",
            "type": "LinkedServiceReference"
        },
        "parameters": {
            "schemaName": {
                "type": "string"
            },
            "tableName": {
                "type": "string"
            }
        },
        "annotations": [],
        "type": "AzureSqlTable",
        "schema": [],
        "typeProperties": {
            "schema": {
                "value": "@dataset().schemaName",
                "type": "Expression"
            },
            "table": {
                "value": "@dataset().tableName",
                "type": "Expression"
            }
        }
    }
}

複製活動的接收器資料集

Copy Activity 將資料從 SQL 資料表複製到 Azure 儲存體 csv 資料夾中的 filebylookup.csv 檔案。 此檔案會由 AzureBlobStorageLinkedService 屬性指定。

{
    "name": "SinkDataset",
    "properties": {
        "linkedServiceName": {
            "referenceName": "AzureBlobStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "parameters": {
            "schema": {
                "type": "string"
            },
            "table": {
                "type": "string"
            }
        },
        "annotations": [],
        "type": "DelimitedText",
        "typeProperties": {
            "location": {
                "type": "AzureBlobStorageLocation",
                "fileName": {
                    "value": "@{dataset().schema}_@{dataset().table}.csv",
                    "type": "Expression"
                },
                "container": "csv"
            },
            "columnDelimiter": ",",
            "escapeChar": "\\",
            "quoteChar": "\""
        },
        "schema": []
    }
}

sourcetable.json

您可以針對 sourcetable.json 檔案使用下列兩種格式。

物件集合

{
   "Id":"1",
   "schema":"dbo",
   "table":"Table1"
}
{
   "Id":"2",
   "schema":"dbo",
   "table":"Table2"
}

物件陣列

[ 
    {
        "Id": "1",
        "schema":"dbo",
        "table":"Table1"
    },
    {
        "Id": "2",
        "schema":"dbo",
        "table":"Table2"
    }
]

限制和因應措施

以下是查閱活動的一些限制和建議的因應措施。

相關內容

請參閱 Azure Data Factory 與 Synapse 管線支援的其他控制流程活動：

• 執行管線活動
• ForEach 活動
• GetMetadata 活動
• Web 活動