함수를 사용하여 `remote_query` 외부 데이터베이스 쿼리

중요합니다

테이블 반환 함수(TVF)를 사용하면 Azure Databricks 내에서 외부 데이터베이스 및 데이터 웨어하우스에 대해 원격 시스템의 고유의 SQL 구문을 사용하여 SQL 쿼리를 직접 실행할 수 있습니다. 이 함수는 쿼리 페더레이션에 대한 유연한 대안을 제공하므로 Databricks SQL로 변환할 필요 없이 원격 데이터베이스의 방언으로 작성된 쿼리를 실행할 수 있습니다.

`remote_query` 쿼리 페더레이션과 비교

다음 표에서는 remote_query 함수와 쿼리 페더레이션 간의 주요 차이점을 요약합니다.

특성	`remote_query` 함수	쿼리 페더레이션
쿼리 구문	원격 데이터베이스의 네이티브 SQL 언어(예: Oracle PL/SQL, BigQuery SQL)를 사용하여 쿼리를 작성합니다.	Databricks SQL 구문을 사용하여 쿼리를 작성합니다. Databricks는 호환되는 작업을 원격 데이터베이스로 변환하고 푸시다운합니다.
사용 사례	수정 없이 실행하려는 원격 데이터베이스의 방언으로 작성된 기존 SQL 쿼리가 있습니다. Databricks SQL에서 사용할 수 없는 데이터베이스별 함수 또는 구문을 사용해야 합니다. 외딴 카탈로그를 만들지 않고 원격 데이터에 임시로 액세스하려고 합니다.	Databricks SQL 구문을 사용하여 외부 데이터를 쿼리하려고 합니다. Unity 카탈로그 외국 카탈로그를 통해 제어된 액세스 권한이 있는 장기 데이터 액세스 패턴이 필요합니다. 일관된 구문을 사용하여 단일 쿼리에서 여러 원본의 데이터를 결합하려고 합니다. Genie 도우미를 사용하여 쿼리를 작성하려고 합니다.
접근 제어	사용자는 연결에 대한 권한이 필요합니다 `USE CONNECTION` . 보기를 통해 권한을 위임할 수 있습니다.	사용자는 외국 카탈로그 개체에 대한 테이블 수준 권한이 필요합니다. 세분화된 컨트롤입니다.

시작하기 전 주의 사항:

작업 공간 요구 사항:

Unity 카탈로그에 사용할 수 있는 작업 영역입니다.

컴퓨팅 요구 사항:

Databricks 런타임 클러스터 또는 SQL 웨어하우스에서 대상 데이터베이스 시스템으로의 네트워크 연결. Lakehouse Federation에 대한 네트워킹 권장 사항을 참조하세요.
Azure Databricks 클러스터는 Databricks Runtime 17.3 이상을 사용해야 합니다.
SQL 웨어하우스는 Pro 또는 Serverless여야 하며 버전 2025.35 이상을 사용해야 합니다.

필요한 권한:

연결을 만들려면 Unity 카탈로그 메타스토어에 대한 권한이 있어야 합니다 CREATE CONNECTION .
함수를 remote_query 사용하려면 연결에 대한 권한 또는 함수를 USE CONNECTION 래핑하는 뷰에 대한 권한이 있어야 합니다SELECT. 단일 사용자 클러스터에는 연결에 MANAGE 대한 권한도 필요합니다.

연결 만들기

이 함수를 remote_query 사용하려면 먼저 외부 데이터베이스에 대한 Unity 카탈로그 연결을 만들어야 합니다. 쿼리 페더레이션에 대한 연결이 이미 만들어진 경우 다시 사용할 수 있습니다.

이 함수는 remote_query 다음 연결 형식에 대한 연결을 지원합니다.

기존 연결을 관리하는 방법에 대한 자세한 내용은 Lakehouse Federation대한 연결 관리를 참조하세요.

연결 액세스 권한 부여

이 함수를 remote_query 사용하려면 연결에 대한 권한(또는 USE CONNECTION 단일 사용자 클러스터에 대한 권한)이 있어야 합니다MANAGE.

GRANT USE CONNECTION ON CONNECTION <connection-name> TO <user-or-group>;

`remote_query` 함수 사용

이 함수는 remote_query 원격 데이터베이스에서 쿼리를 실행하고 Databricks SQL 쿼리에서 사용할 수 있는 테이블로 결과를 반환합니다.

Syntax

SELECT * FROM remote_query(
  '<connection-name>',
  <option-key> => '<option-value>'
  [, <option-key> => '<option-value>' ...]
)

필수 매개 변수

connection-name: 사용할 Unity 카탈로그 연결의 이름입니다.

다른 모든 필수 매개 변수는 연결 유형에 따라 다릅니다. 자세한 내용은 커넥터 관련 옵션을 참조하세요.

커넥터 관련 옵션

사용 가능한 옵션은 연결 유형에 따라 다릅니다. 다음 표에서는 각 커넥터에 대한 옵션을 설명합니다.

MySQL, PostgreSQL, SQL Server, Redshift 및 Teradata

매개 변수	필수	Description
`database`	Yes	원격 시스템의 데이터베이스 이름입니다.
`query`	예(또는 `dbtable`)	원격 데이터베이스에서 실행할 SQL 쿼리 문자열입니다. 와 함께 `dbtable`사용할 수 없습니다.
`dbtable`	예(또는 `query`)	쿼리할 테이블 이름입니다. 와 함께 `query`사용할 수 없습니다.
`fetchsize`	아니오	왕복당 가져올 행 수입니다. 값이 클수록 성능이 향상되지만 더 많은 메모리를 사용할 수 있습니다. 기본값: 0(드라이버 기본값 사용).
`partitionColumn`	아니오	병렬 데이터 페치에 사용할 균일하게 분산된 값이 있는 열입니다. `lowerBound`, `upperBound` 및 `numPartitions`와 함께 사용해야 합니다. 옵션과 함께 `query` 사용할 수 없습니다.
`lowerBound`	아니오	파티션 열의 최소값입니다. `partitionColumn`, `upperBound` 및 `numPartitions`와 함께 사용해야 합니다.
`upperBound`	아니오	파티션 열의 최대값입니다. `partitionColumn`, `lowerBound` 및 `numPartitions`와 함께 사용해야 합니다.
`numPartitions`	아니오	데이터 가져오기에 사용할 병렬 연결 수입니다. 너무 높음(수백)을 설정하지 마세요. `partitionColumn`, `lowerBound` 및 `upperBound`와 함께 사용해야 합니다.

비고

파티션 매개 변수를 사용하는 경우 네 개의 매개 변수(partitionColumn, lowerBound, upperBound, numPartitions)를 모두 함께 지정해야 하며 dbtable 대신 query 옵션을 사용해야 합니다.

Oracle

매개 변수	필수	Description
`service_name`	Yes	Oracle 서비스 이름(`database` 대신 사용)입니다.
`query`	예(또는 `dbtable`)	원격 데이터베이스에서 실행할 SQL 쿼리 문자열입니다. 와 함께 `dbtable`사용할 수 없습니다.
`dbtable`	예(또는 `query`)	쿼리할 테이블 이름입니다. 와 함께 `query`사용할 수 없습니다.
`fetchsize`	아니오	왕복당 가져올 행 수입니다. 값이 클수록 성능이 향상되지만 더 많은 메모리를 사용할 수 있습니다. 기본값: 0(드라이버 기본값 사용).
`partitionColumn`	아니오	병렬 데이터 페치에 사용할 균일하게 분산된 값이 있는 열입니다. `lowerBound`, `upperBound` 및 `numPartitions`와 함께 사용해야 합니다. 옵션과 함께 `query` 사용할 수 없습니다.
`lowerBound`	아니오	파티션 열의 최소값입니다. `partitionColumn`, `upperBound` 및 `numPartitions`와 함께 사용해야 합니다.
`upperBound`	아니오	파티션 열의 최대값입니다. `partitionColumn`, `lowerBound` 및 `numPartitions`와 함께 사용해야 합니다.
`numPartitions`	아니오	데이터 가져오기에 사용할 병렬 연결 수입니다. 너무 높음(수백)을 설정하지 마세요. `partitionColumn`, `lowerBound` 및 `upperBound`와 함께 사용해야 합니다.

비고

Snowflake

매개 변수	필수	Description
`database`	Yes	Snowflake의 데이터베이스 이름입니다.
`query`	예(또는 `dbtable`)	원격 데이터베이스에서 실행할 SQL 쿼리 문자열입니다. 와 함께 `dbtable`사용할 수 없습니다.
`dbtable`	예(또는 `query`)	쿼리할 테이블 이름(단일 부분 이름 또는 다중 파트 이름)입니다. 와 함께 `query`사용할 수 없습니다.
`schema`	아니오	Snowflake의 스키마 이름입니다. 기본값: `public`.
`query_timeout`	아니오	쿼리 시간 제한(초)입니다. 기본값: 0(시간 제한 없음)
`partition_size_in_mb`	아니오	병렬 데이터 페치에 필요한 파티션 크기(메가바이트)입니다. 기본값: 100MB

BigQuery

매개 변수	필수	Description
`query`	예(또는 `dbtable`)	원격 데이터베이스에서 실행할 SQL 쿼리 문자열입니다. 와 함께 `dbtable`사용할 수 없습니다.
`dbtable`	예(또는 `query`)	쿼리할 테이블 이름입니다. 와 함께 `query`사용할 수 없습니다.
`materializationDataset`	결과의 구체화가 필요한 경우 예입니다. 조건으로 `query`이(가) 지정되고 `dbtable`이(가) 뷰를 가리키는 경우 구체화가 필요합니다.	임시 테이블이 구체화되는 BigQuery 데이터 세트 이름입니다. 임시 테이블의 기본 TTL(Time to Live)은 24시간입니다.
`materializationProject`	아니오	구체화를 위한 BigQuery 프로젝트 ID입니다. 연결에 지정된 프로젝트가 기본값으로 설정됩니다.
`materializationEnabled`	아니오	쿼리에 구체화를 사용하도록 설정할지 여부입니다. 쿼리 뷰를 위해 `true`로 설정하십시오. 기본값: `false` 지정된 경우 `dbtable` (지정된 `true` 경우 `query` )
`parentProject`	아니오	청구를 위한 부모 프로젝트 ID입니다.

중요합니다

모든 BigQuery 매개 변수는 대/소문자를 구분합니다.

추가 푸시다운 컨트롤 옵션

함수를 remote_query Databricks SQL 작업과 결합할 수 있으며 이러한 작업의 대부분도 푸시다운할 수 있습니다. 푸시다운할 수 있는 Databricks SQL 작업을 제어할 수도 있습니다. 이러한 옵션은 모든 연결 형식에 적용되며 대/소문자를 구분하지 않습니다.

매개 변수	Default	Description
`pushdown.limit.enabled`	`true`	원격 데이터베이스에 대한 푸시다운 `LIMIT` 절을 사용하거나 사용하지 않도록 설정합니다.
`pushdown.offset.enabled`	`true`	원격 데이터베이스에 대한 푸시다운 `OFFSET` 절을 사용하거나 사용하지 않도록 설정합니다.
`pushdown.filters.enabled`	`true`	원격 데이터베이스에 대한 푸시다운 `WHERE` 필터를 사용하거나 사용하지 않도록 설정합니다.
`pushdown.aggregates.enabled`	`true`	집계 함수(`COUNT`, , `SUM`, `AVGMAX`,`MIN`)를 원격 데이터베이스에 푸시다운하도록 설정하거나 사용하지 않도록 설정합니다.
`pushdown.sortLimit.enabled`	`true`	원격 데이터베이스로 상위 N개 쿼리(`ORDER BY` 및 `LIMIT`의 조합)를 푸시할지 여부를 활성화하거나 비활성화합니다.

기본적으로 모든 푸시다운은 사용하도록 설정됩니다. 문제 해결에 필요한 경우 특정 푸시다운을 사용하지 않도록 설정하거나 특정 원격 데이터베이스와의 호환성 문제를 해결할 수 있습니다.

액세스를 뷰를 통해 위임하기

함수를 뷰로 래핑하여 사용자에게 직접 USE CONNECTION 권한을 부여하지 않고, 원격 데이터에 대한 액세스를 위임할 수 있습니다. 이 방법은 다음과 같은 이점이 있습니다.

간소화된 액세스 제어: 권한을 관리하는 SELECT 대신 보기에 대한 권한을 부여 USE CONNECTION 합니다.
데이터 보안: 뷰 쿼리를 정의하여 사용자가 액세스할 수 있는 열과 행을 제어합니다.
계보 추적: 직접 연결 사용이 아닌 뷰 계보를 통해 데이터 액세스를 추적합니다.

보기를 통해 액세스를 위임하려면 다음을 수행합니다.

함수를 호출하는 뷰를 만듭니다.remote_query

CREATE VIEW sales_data_view AS
SELECT * FROM remote_query(
  'my_connection',
  database => 'sales_db',
  query => 'SELECT region, product, revenue FROM sales'
);

보기에 대한 SELECT 권한을 사용자 또는 그룹에 부여합니다.
```
GRANT SELECT ON VIEW sales_data_view TO <user-or-group>;
```
이제 사용자는 권한 없이 보기를 쿼리할 수 있습니다.USE CONNECTION
```
SELECT * FROM sales_data_view WHERE region = 'US';
```

중요합니다

보기 소유자는 연결에 대한 권한이 있어야 합니다 USE CONNECTION . 사용자가 보기를 쿼리할 때 연결 액세스 검사는 쿼리 사용자의 권한이 아니라 뷰 소유자의 권한을 사용하여 수행됩니다.

예시

기본 쿼리 실행

PostgreSQL 데이터베이스에서 쿼리를 실행합니다.

SELECT * FROM remote_query(
  'my_postgres_connection',
  database => 'sales_db',
  query => 'SELECT * FROM orders WHERE order_date > CURRENT_DATE - INTERVAL \'30 days\''
);

특정 테이블 쿼리

MySQL 테이블을 직접 쿼리합니다.

SELECT * FROM remote_query(
  'my_mysql_connection',
  database => 'inventory',
  dbtable => 'my_schema.products'
);

서비스 이름을 가진 Oracle

Oracle 데이터베이스 쿼리:

SELECT * FROM remote_query(
  'my_oracle_connection',
  service_name => 'ORCL',
  query => 'SELECT * FROM customers WHERE ROWNUM <= 1000'
);

BigQuery 질의

Google BigQuery 쿼리:

SELECT * FROM remote_query(
  'my_bigquery_connection',
  materializationDataset => 'analytics',
  query => 'SELECT * FROM `project.dataset.table` WHERE created_date > DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)'
);

Snowflake 쿼리

Snowflake 쿼리:

SELECT * FROM remote_query(
  'my_snowflake_connection',
  database => 'ANALYTICS_DB',
  query => 'SELECT * FROM SALES WHERE SALE_DATE >= DATEADD(day, -30, CURRENT_DATE())'
);

분할을 사용하여 성능 튜닝

SQL Server 테이블에서 병렬로 데이터를 가져옵니다.

SELECT * FROM remote_query(
  'my_sqlserver_connection',
  database => 'sales',
  dbtable => 'transactions',
  partitionColumn => 'transaction_id',
  lowerBound => '0',
  upperBound => '1000000',
  numPartitions => '10',
  fetchsize => '1000'
);

Databricks SQL 작업과 결합

추가 필터 및 변환을 적용합니다.

SELECT customer_id, SUM(amount) as total_amount
FROM remote_query(
  'my_postgres_connection',
  database => 'orders_db',
  query => 'SELECT customer_id, amount, order_date FROM orders'
)
WHERE order_date >= '2025-01-01'
GROUP BY customer_id
HAVING total_amount > 1000
ORDER BY total_amount DESC
LIMIT 100;

위임된 액세스에 대한 보기 만들기

뷰를 생성하여 함수를 remote_query 래핑합니다. 보기에 대한 권한이 있는 SELECT 사용자는 기본 연결에 대한 권한 없이 USE CONNECTION 데이터를 쿼리할 수 있습니다.

CREATE VIEW sales_summary AS
SELECT * FROM remote_query(
  'my_mysql_connection',
  database => 'sales',
  query => 'SELECT region, product, SUM(revenue) as total_revenue FROM sales_data GROUP BY region, product'
);

GRANT SELECT ON VIEW sales_summary TO <user-or-group>;

푸시다운 동작 제어

함수를 remote_query 사용하는 경우 Databricks는 지정한 쿼리를 넘어 원격 데이터베이스에 대한 추가 작업을 푸시다운할 수 있습니다. 이 기능은 함수를 사용하는 remote_query 뷰를 쿼리할 때 유용합니다.

다음 작업을 하향 처리할 수 있습니다.

필터: 원격 쿼리 결과에 적용되는 WHERE 절
프로젝션: 열 선택(SELECT 특정 열)
Limit: LIMIT 반환되는 행 수를 제한하는 절
오프셋: OFFSET 행을 건너뛰기 위한 조건
집계: 집계 함수(예: COUNT, SUM, AVGMAX)MIN
Top-N: 상위/하위 N 쿼리를 위한 ORDER BYLIMIT의 조합

푸시다운 지원은 데이터 원본에 따라 다릅니다. 자세한 내용은 특정 연결 유형에 대한 설명서를 참조하세요.

문제 해결 또는 호환성을 위해 특정 푸시다운을 사용하지 않도록 설정합니다.

SELECT * FROM remote_query(
  'my_postgres_connection',
  database => 'analytics',
  query => 'SELECT * FROM complex_view',
  `pushdown.aggregates.enabled` => 'false',
  `pushdown.filters.enabled` => 'false'
);

제한점

읽기 전용 작업: remote_query 함수는 SELECT 쿼리만 지원합니다. 데이터 수정 작업(INSERT, , UPDATEDELETE, MERGE), DDL 작업(CREATE, DROP, ALTER) 및 저장 프로시저는 지원되지 않습니다.
쿼리 유효성 검사: 제공하는 쿼리는 원격 데이터베이스에서 직접 실행됩니다. Databricks는 스키마 검사를 수행하여 쿼리가 읽기 전용인지 확인하지만, 구문 및 의미 체계 유효성 검사는 원격 데이터베이스에서 수행됩니다.

Troubleshooting

권한 오류

사용 권한 오류가 표시되는 경우 다음을 확인합니다.

연결에 대한 USE CONNECTION 권한 또는 함수를 래핑하는 보기에 대한 SELECT 권한이 있습니다.
연결의 자격 증명에는 원격 데이터베이스에 대한 적절한 권한이 있습니다.

예제 오류:

PERMISSION_DENIED: User does not have USE CONNECTION on Connection 'my_connection'

해결 방법:

GRANT USE CONNECTION ON CONNECTION my_connection TO <user-or-group>;

지원되지 않는 매개 변수

지원되지 않는 매개 변수에 대한 오류가 표시되는 경우 연결 형식에 올바른 매개 변수를 사용하고 있는지 확인합니다. 오류 메시지는 허용된 매개 변수를 나열합니다.

예제 오류:

REMOTE_QUERY_FUNCTION_UNSUPPORTED_CONNECTOR_PARAMETERS: The following parameters are not supported for connection type 'postgresql': 'materializationDataset'. Allowed parameters for this connection type are: 'database', 'query', 'dbtable', 'fetchsize', 'partitionColumn', 'lowerBound', 'upperBound', 'numPartitions'.

해결 방법: 지원되지 않는 매개 변수를 제거하고 연결 형식에 올바른 매개 변수를 사용합니다.

DML 작업이 지원되지 않음

함수는 remote_query 읽기 전용 SELECT 쿼리만 지원합니다.

예제 오류:

DML_OPERATIONS_NOT_SUPPORTED_FOR_REMOTE_QUERY_FUNCTION: Data modification operations are not supported in remote_query function.

해결 방법: 쿼리에서 모든 INSERT, UPDATEDELETE 또는 DDL 문을 제거합니다. SELECT 문장만 사용하세요.

추가 리소스

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-01-30

다음을 통해 공유

함수를 사용하여 remote_query 외부 데이터베이스 쿼리

remote_query 쿼리 페더레이션과 비교

시작하기 전 주의 사항:

연결 만들기

연결 액세스 권한 부여

remote_query 함수 사용

Syntax

필수 매개 변수

커넥터 관련 옵션

MySQL, PostgreSQL, SQL Server, Redshift 및 Teradata

Oracle

Snowflake

BigQuery

추가 푸시다운 컨트롤 옵션

액세스를 뷰를 통해 위임하기

예시

기본 쿼리 실행

특정 테이블 쿼리

서비스 이름을 가진 Oracle

BigQuery 질의

Snowflake 쿼리

분할을 사용하여 성능 튜닝

Databricks SQL 작업과 결합

위임된 액세스에 대한 보기 만들기

푸시다운 동작 제어

제한점

Troubleshooting

권한 오류

지원되지 않는 매개 변수

DML 작업이 지원되지 않음

추가 리소스

피드백

추가 리소스

함수를 사용하여 `remote_query` 외부 데이터베이스 쿼리

`remote_query` 쿼리 페더레이션과 비교

`remote_query` 함수 사용