BigQuery DataFrames용 Python 함수 맞춤설정

BigQuery DataFrames를 사용하면 맞춤 Python 함수를 BigQuery DataFrames 객체에서 대규모로 실행할 수 있는 BigQuery 아티팩트로 변환할 수 있습니다. 이 확장성 지원을 사용하면 BigQuery DataFrames 및 SQL API로 가능한 작업을 넘어 작업을 실행할 수 있으므로 오픈소스 라이브러리를 활용할 수 있습니다.

이 확장성 메커니즘에는 사용자 정의 함수와 원격 함수의 두 가지 변형이 있습니다.

필요한 역할

이 문서의 태스크를 완료하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

역할 부여 방법에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

사용자 정의 함수(UDF)

UDF(프리뷰)를 사용하면 맞춤 Python 함수를 Python UDF로 변환할 수 있습니다. 사용 예시는 영구 Python UDF 만들기를 참고하세요.

BigQuery DataFrames에서 UDF를 만들면 지정된 데이터 세트에 Python UDF로 BigQuery 루틴이 생성됩니다. 지원되는 전체 매개변수 집합은 bigframes.pandas.udf를 참고하세요.

요구사항

BigQuery DataFrames UDF를 사용하려면 프로젝트에서 BigQuery API를 사용 설정하세요. 프로젝트에 bigquery_connection 매개변수를 제공하는 경우 BigQuery Connection API도 사용 설정해야 합니다.

삭제

Google Cloud 콘솔 또는 다른 도구에서 직접 클라우드 아티팩트를 정리하는 것 외에도 bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) 명령어를 사용하여 명시적 이름 인수로 생성된 BigQuery DataFrames UDF를 정리할 수 있습니다.

제한사항

  • UDF의 코드는 독립적이어야 합니다. 즉, 함수 본문 외부에 정의된 가져오기 또는 변수에 대한 참조가 포함되어서는 안 됩니다.
  • UDF의 코드는 Python 3.11과 호환되어야 합니다. 이는 클라우드에서 코드가 실행되는 환경이기 때문입니다.
  • 함수 코드의 사소한 변경사항(예: 변수 이름 변경 또는 새 줄 삽입) 후에 UDF 정의 코드를 다시 실행하면 이러한 변경사항이 함수의 동작에 중요하지 않더라도 UDF가 다시 생성됩니다.
  • 사용자 코드는 BigQuery 루틴에 대한 읽기 액세스 권한이 있는 사용자에게 표시되므로 민감한 콘텐츠는 주의해서만 포함해야 합니다.
  • 한 프로젝트에 BigQuery 위치에 Cloud Run Functions를 한 번에 최대 1,000개까지 사용할 수 있습니다.

BigQuery DataFrames UDF는 사용자 정의 BigQuery Python 함수를 배포하며 관련 제한사항이 적용됩니다.

원격 함수

BigQuery DataFrames를 사용하면 맞춤 스칼라 함수를 BigQuery 원격 함수로 변환할 수 있습니다. 사용 예시는 원격 함수 만들기를 참고하세요. 지원되는 전체 매개변수 집합은 remote_function을 참고하세요.

BigQuery DataFrames에서 원격 함수를 만들면 다음이 생성됩니다.

  • Cloud Run functions

  • BigQuery 연결.

    기본적으로 bigframes-default-connection이라는 연결이 사용됩니다. 원하는 경우 사전 구성된 BigQuery 연결을 사용할 수 있습니다. 이 경우 연결 만들기가 생략됩니다. 기본 연결의 서비스 계정에 Cloud Run 역할(roles/run.invoker)이 부여됩니다.

  • BigQuery 연결로 만든 Cloud Run functions를 사용하는 BigQuery 원격 함수

요구사항

BigQuery DataFrames 원격 함수를 사용하려면 다음 API를 사용 설정해야 합니다.

BigQuery DataFrames 원격 함수를 사용하는 경우에는 기본 BigQuery 연결을 사용할 때는 프로젝트 IAM 관리자 역할 (roles/resourcemanager.projectIamAdmin)이 필요하고 사전 구성된 연결을 사용할 때는 브라우저 역할 (roles/browser)이 필요합니다. bigframes.pandas.options.bigquery.skip_bq_connection_check 옵션을 True로 설정하여 이 요구사항을 피할 수 있습니다. 이 경우 존재 또는 권한 확인 없이 연결 (기본 또는 사전 구성)을 그대로 사용합니다. 사전 구성된 연결을 사용하고 연결 확인을 건너뛰는 경우 다음을 확인합니다.

  • 연결이 올바른 위치에 생성됩니다.
  • BigQuery DataFrames 원격 함수를 사용하는 경우 서비스 계정에 프로젝트에 대한 Cloud Run 호출자 역할(roles/run.invoker)이 있습니다.

연결 보기 및 관리

BigQuery 연결은 커스텀 함수 정의에 제공한 이름을 사용하여 BigQuery DataFrames 세션과 동일한 위치에 생성됩니다. 연결을 보고 관리하려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 원격 함수를 만든 프로젝트를 선택합니다.

  3. 왼쪽 창에서 탐색기를 클릭합니다.

    강조 표시된 탐색기 창 버튼

  4. 탐색기 창에서 프로젝트를 펼친 다음 연결을 클릭합니다.

BigQuery 원격 함수는 지정한 데이터 세트에 생성되거나 숨겨진 데이터 세트 유형인 익명 데이터 세트에 생성됩니다. 원격 함수를 만들 때 이름을 설정하지 않으면 BigQuery DataFrames는 bigframes 프리픽스로 시작하는 기본 이름을 적용합니다. 사용자가 지정한 데이터 세트에서 만든 원격 함수를 보고 관리하려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 원격 함수를 만든 프로젝트를 선택합니다.

  3. 왼쪽 창에서 탐색기를 클릭합니다.

    강조 표시된 탐색기 창 버튼

  4. 탐색기 창에서 프로젝트를 펼친 다음 데이터 세트를 클릭합니다.

  5. 원격 함수를 만든 데이터 세트를 클릭합니다.

  6. 루틴 탭을 클릭합니다.

Cloud Run functions를 보고 관리하려면 다음 단계를 따르세요.

  1. Cloud Run 페이지로 이동합니다.

    Cloud Run으로 이동

  2. 함수를 만든 프로젝트를 선택합니다.

  3. 사용 가능한 서비스 목록에서 함수 배포 유형을 기준으로 필터링합니다.

  4. BigQuery DataFrames에서 만든 함수를 식별하려면 bigframes 접두사가 있는 함수 이름을 찾습니다.

삭제

Cloud 아티팩트를 Google Cloud 콘솔 또는 다른 도구로 직접 정리하는 것 외에도 명시적인 이름 인수 없이 생성된 BigQuery 원격 함수와 연결된 Cloud Run Functions를 다음과 같은 방법으로 삭제할 수 있습니다.

  • BigQuery DataFrames 세션의 경우 session.close() 명령어 사용
  • 기본 BigQuery DataFrames 세션의 경우 bigframes.pandas.close_session() 명령어 사용
  • session_id가 포함된 이전 세션의 경우 bigframes.pandas.clean_up_by_session_id(session_id) 명령어 사용

명시적 이름 인수로 생성된 BigQuery 원격 함수와 연결된 Cloud Run functions도 bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) 명령어를 사용하여 정리할 수 있습니다.

제한사항

  • 원격 함수는 처음 만들 때 사용할 수 있게 되기까지 약 90초가 걸립니다. 패키지 종속 항목이 추가되면 지연 시간이 늘어날 수 있습니다.
  • 함수 코드 안팎에서 사소한 변경사항(예: 변수 이름 변경, 새 줄 삽입, 노트북에 새 셀 삽입)이 발생한 후 원격 함수 정의 코드를 다시 실행하면 이러한 변경사항이 함수의 동작에 영향을 미치지 않더라도 원격 함수가 다시 생성될 수 있습니다.
  • 사용자 코드는 Cloud Run functions에 대한 읽기 액세스 권한이 있는 사용자에게 표시되므로 민감한 콘텐츠는 주의해서만 포함해야 합니다.
  • 한 프로젝트에 리전에서 한 번에 최대 1,000개의 Cloud Run functions를 보유할 수 있습니다. 자세한 내용은 할당량을 참조하세요.

다음 단계