빅쿼리 ObjectRef 사용법: 이미지·문서를 SQL로 분석하는 순서

빅쿼리 ObjectRef는 Cloud Storage에 있는 이미지·오디오·PDF 같은 파일을 가리키는 값이어서, 파일을 표의 한 칸처럼 두고 SQL로 Gemini 모델에 넘겨 분석하게 해 준다. 구글 클라우드는 2026년 10월 22일 블로그에서 ObjectRef와 멀티모달 데이터 분석 기능을 정식 출시(GA)했다고 밝혔다(구글 클라우드 블로그). ObjectRef를 쓰려면 파일을 읽을 권한 방식(직접 접근 또는 연결)을 먼저 정하고, OBJ.MAKE_REF로 값을 만든 뒤 AI 함수에 넘기면 된다.

ObjectRef가 필요한 상황: 파일은 버킷에, 숫자는 표에 따로 있을 때

상품 이미지는 버킷에 있고 매출은 표에 있어서, "이 이미지의 상품이 규정을 어겼는지" 같은 질문을 SQL 한 줄로 못 던지는 상황에서 ObjectRef를 쓴다. 도서관에 비유하면 책 본문은 서가에 있고 표에는 청구기호만 적혀 있는 것과 같다. 청구기호가 있으면 책을 직접 들고 다니지 않아도 사서가 서가에서 꺼내 준다. ObjectRef가 그 청구기호 역할을 하고, 빅쿼리가 사서처럼 파일을 꺼내 Gemini에 전달한다. 다만 청구기호는 위치만 알려 줄 뿐이라 파일을 꺼낼 권한이 따로 있어야 한다.

공식 문서에 따르면 ObjectRef는 Cloud Storage 객체를 참조하는 미리 정해진 구조의 STRUCT 타입이다. 필드는 네 개다(ObjectRef 사용 문서).

필드	담는 값
uri	파일 주소(필수). 예: gs://버킷/폴더/파일.png
version	객체의 generation(파일 버전)
authorizer	파일을 읽을 때 쓰는 연결 ID. 없으면 NULL
details	Cloud Storage 메타데이터 또는 오류 정보(JSON)

GA에서 달라진 점: 연결 없이도 쓰고, 여러 파일을 한 번에 넘긴다

GA로 바뀐 것은 세 가지다. 첫째, 사용자 개인의 IAM 권한(End User Credentials)으로 ObjectRef를 바로 조회하는 방식이 추가돼 ad-hoc 분석을 연결 없이 할 수 있다. 프리뷰에서는 BigQuery 연결 설정이 필요했고, 구글은 서비스 계정으로 도는 운영 파이프라인에는 여전히 연결 방식을 권한다. 둘째, 객체 테이블, Cloud Storage insights 데이터셋, 일반 테이블의 문자열 URI에서 ObjectRef를 만들 수 있다. 셋째, ObjectRef를 배열로 묶어 문서 여러 개를 비교하거나 이미지 시퀀스를 한 번의 호출로 분석할 수 있다(구글 클라우드 블로그).

구글은 모든 BigQuery 에디션과 온디맨드 요금제에서 GA라고 밝혔다. AI 함수는 기본으로 Optimized Mode를 써서 소비하는 토큰 수를 줄인다고 한다.

ObjectRef 만드는 법: OBJ.MAKE_REF 한 줄

문자열 URI가 이미 있는 테이블이라면 OBJ.MAKE_REF 함수로 ObjectRef를 만든다. 파일 형식은 자동으로 감지된다. 객체 테이블을 쓰는 경우에는 테이블의 ref 열에 ObjectRef가 이미 들어 있다.

-- 문자열 URI에서 만들기
SELECT product_id, OBJ.MAKE_REF(image_uri) AS image_ref
FROM ecommerce.vendor_uploads;

-- 연결을 지정해 만들기 (형식: 리전.연결이름)
SELECT OBJ.MAKE_REF(image_uri, "us.myconnection") AS image_ref
FROM ecommerce.vendor_uploads;

-- 버킷 폴더를 객체 테이블로 만들기
CREATE EXTERNAL TABLE mydataset.images
WITH CONNECTION `us.myconnection`
OPTIONS (uris=["gs://mybucket/images/*"], object_metadata="SIMPLE");

위 연결 지정 형식과 객체 테이블 예시는 공식 문서에 나온 구문이다(ObjectRef 사용 문서). 객체 테이블의 ref 열은 테이블을 만들 때 쓴 연결을 authorizer로 갖는다.

ObjectRef 권한: 직접 접근과 연결 접근 중 무엇을 고를까

두 방식은 파일을 누구의 권한으로 읽느냐가 다르다. 구글의 안내를 따르면 한 번 시험해 보는 분석은 직접 접근, 서비스 계정으로 정기 실행하는 파이프라인은 연결 접근이 맞다. 연결 접근만 다른 프로젝트의 버킷을 읽을 수 있다는 점도 고르는 기준이 된다.

구분	직접 접근	연결(위임) 접근
authorizer	NULL	연결 ID 지정
파일을 읽는 주체	쿼리를 실행한 사용자	연결의 서비스 계정
필요한 권한	사용자에게 객체 읽기 권한	서비스 계정에 Storage Object Viewer 등, 사용자에게 BigQuery ObjectRef Reader 등
다른 프로젝트 버킷	연결 없이 AI 함수를 쓰면 같은 프로젝트만	가능

표의 내용은 공식 문서가 설명하는 그대로다(ObjectRef 사용 문서). 연결로 AI.GENERATE를 쓸 때는 연결의 서비스 계정에 Agent Platform User 역할도 필요하다. VPC Service Controls 경계 안에서는 연결 방식의 ObjectRef를 AI 함수가 처리하지 못하므로, 이때는 OBJ.MAKE_REF(uri)로 직접 접근을 쓴다.

ObjectRef로 이미지 분석 쿼리 쓰는 법: 분류·필터·생성

ObjectRef를 만들었으면 AI 함수의 입력으로 그대로 넣는다. 구글 블로그는 대표 함수로 AI.CLASSIFY(분류), AI.IF(WHERE 조건 필터), AI.GENERATE(텍스트·구조화 출력 생성), AI.AGG(여러 행 요약)를 든다.

이미지로 조건을 거는 대표 예시는 공식 블로그의 상품 규정 점검 쿼리다. 어제 올라온 상품 이미지 중 금지 품목이 있는 것만 골라낸다.

SELECT product_id, seller_id
FROM ecommerce.vendor_uploads
WHERE upload_date >= CURRENT_DATE() - 1
  AND AI.IF(
    "Does this product image contain a restricted item or policy violation?",
    OBJ.MAKE_REF(image_uri)
  );

구글 블로그의 두 번째 예시는 오디오다. 콜센터 녹음 파일의 주소를 OBJ.MAKE_REF로 바꾸고 AI.CLASSIFY에 "카드 분실", "결제 거절" 같은 분류 항목 목록을 주면 문의 유형 열이 만들어진다. 구조화된 결과가 필요하면 AI.GENERATE에 output_schema를 지정하고, ObjectRef 배열을 넣으면 공식 로그인 화면 캡처와 의심 페이지 캡처를 한 호출에서 비교하는 피싱 판별도 한다(구글 클라우드 블로그). 여러 행을 하나로 요약하는 AI.AGG는 빅쿼리 AI.AGG 함수 사용법에서 구문과 한도를 따로 다뤘다.

첫 실행이 제대로 됐는지 확인하는 법

AI 함수는 행마다 모델을 호출하므로 처음에는 파일 몇 개짜리 작은 테이블로 시험하는 편이 안전하다. 공식 튜토리얼은 BigQuery 처리량, Cloud Storage 읽기, 모델 호출 세 가지에 비용이 발생한다고 안내한다(멀티모달 SQL 튜토리얼).

1. OBJ.MAKE_REF 결과 열을 SELECT해서 uri 필드에 파일 주소가 들어 있는지 본다.
2. ObjectRef의 details.errors에 code, message, source가 담겨 있지 않은지 확인한다. 권한이나 주소가 틀리면 오류가 여기에 남는다.
3. AI 함수 결과를 원본 파일 몇 개와 눈으로 대조한다. 분류 결과가 파일 내용과 맞으면 대상 행을 늘린다.
4. 대상 행을 늘리기 전에 하루 사용량 상한이 필요한지 따져 보고, 필요하면 프로젝트별 AI 토큰 쿼터를 건다.

실습용 데이터가 필요하면 구글의 멀티모달 SQL 튜토리얼이 공개 샘플(Cymbal 펫 스토어 이미지)로 이미지 설명 생성, 카테고리 지정, 임베딩 검색까지 안내한다. 쿼리를 처음부터 쓰기 부담스러우면 SQL 편집기의 Gemini 버튼으로 주석을 SQL로 바꿔 시작할 수 있다.

ObjectRef 오류가 날 때 자주 하는 실수

• 연결 없이 AI 함수를 쓰면서 다른 프로젝트의 버킷을 가리킨 경우: 직접 접근은 쿼리가 실행되는 프로젝트의 버킷만 읽는다. 다른 프로젝트 파일은 연결(위임) 접근으로 바꾼다.
• 연결의 서비스 계정에 읽기 권한을 주지 않은 경우: 서비스 계정에 Storage Object Viewer 같은 역할이 없으면 파일을 못 읽고 details.errors에 오류가 남는다.
• VPC Service Controls 경계 안에서 객체 테이블의 ref 열을 그대로 쓴 경우: 이 열은 항상 연결을 authorizer로 써서 실패한다. OBJ.MAKE_REF(uri)로 다시 만들어 직접 접근으로 처리한다(ObjectRef 사용 문서).

자주 묻는 질문

ObjectRef는 Cloud Storage 말고 다른 곳의 파일도 가리킬 수 있나요?

공식 문서는 ObjectRef를 Cloud Storage 객체를 참조하는 타입으로 정의한다(ObjectRef 사용 문서). 문서에 다른 저장소를 가리키는 방법은 나오지 않는다.

연결을 만들지 않고 AI.GENERATE를 쓸 수 있나요?

된다. authorizer가 NULL인 직접 접근이면 실행한 사용자의 권한으로 파일을 읽고, 이때 버킷과 객체는 쿼리가 실행되는 프로젝트와 같은 프로젝트에 있어야 한다(ObjectRef 사용 문서).

ObjectRef 값이 바뀌면 원본 파일도 바뀌나요?

ObjectRef는 uri와 version 등 파일을 가리키는 정보를 담은 값이다. OBJ.MAKE_REF의 authorizer 인자로 접근에 쓸 연결을 바꾸거나 NULL로 제거할 수 있고, 이는 읽기 방식을 바꾸는 것이다(ObjectRef 사용 문서).