Salesforce: 개체 쿼리 단계

설명

Salesforce의 Bulk API 2.0으로 표준 또는 사용자 지정 Salesforce 개체 하나를 프로젝트 테이블로 읽어 옵니다. Salesforce 연결, 개체, 필드를 선택하면 이 단계가 쿼리를 만들고 전체 결과 집합을 페이지 단위로 읽어 각 열을 Salesforce가 선언한 유형으로 저장합니다. 작성할 쿼리는 없습니다.

Salesforce는 REST API를 통해 클라우드에서 직접 접근하므로 이 단계에는 PlaidLink 에이전트가 필요하지 않습니다.

구성

필드	필수	참고
Salesforce 연결	예	데이터를 읽을 Salesforce 연결입니다. 연결은 도구 > 연결에서 관리합니다.
환경	아니요	연결의 환경 중 읽을 환경입니다. 샌드박스 환경은 샌드박스 조직을, 프로덕션 환경은 프로덕션을 가리키게 하십시오. 기본값은 연결의 `default` 환경입니다.
개체	예	개체의 API 이름입니다(`Account`, `Opportunity`, `Invoice__c`). 선택기에는 연결의 Run As 사용자가 쿼리할 수 있는 개체가 나열되며 직접 입력한 이름도 허용하므로, 검색을 사용할 수 없는 동안에도 저장된 단계는 계속 작동합니다.
대상 테이블	예	행을 저장할 프로젝트 테이블입니다.
삭제되거나 보관된 레코드 포함	아니요	Salesforce `queryAll`과 마찬가지로 휴지통의 레코드와 보관된 활동도 함께 읽습니다.
필드	예	추출할 필드를 선택합니다. 하나 이상 필요합니다. Bulk API 2.0은 개체 전체 선택을 거부하므로 열 목록은 항상 명시해야 합니다.
필터	아니요	Salesforce에서 추출 범위를 좁힙니다. Salesforce에서 필터링을 참조하십시오.
창 태그	아니요	추출 창의 이름을 지정합니다. 추출 창은 한 번만 실행됩니다를 참조하십시오.

Id는 선택 여부와 관계없이 항상 포함됩니다. 다시 실행할 때마다 병합하는 기준 키이기 때문입니다. 통화 필드는 개체에 CurrencyIsoCode가 있으면 해당 필드도 함께 가져옵니다.

행이 저장되는 방식

실행할 때마다 필터가 적용된 개체 전체를 읽어, 각 페이지를 Id 기준으로 대상 테이블에 병합합니다. 테이블에 이미 있는 행은 그 자리에서 교체되므로 중단된 실행을 재개해도 같은 행이 두 번 저장되지 않습니다.

저장되는 열은 첫 페이지 데이터로 추측한 유형이 아니라 Salesforce가 자체 필드 메타데이터에서 선언한 유형을 사용합니다. 필드 선택기의 저장 형식 열이 바로 그 선언된 유형이므로, 양식에서 승인한 모양이 곧 테이블이 갖게 되는 모양입니다.

유형별 저장 형식

Salesforce 필드 유형	저장 형식
`id`, `reference`, `string`, `textarea`, `phone`, `url`, `email`, `picklist`, `multipicklist`, `combobox`	텍스트
`boolean`	부울
`date`	날짜
`datetime`	타임스탬프
`time`	시간
`int`	정수, 또는 필드가 10자리 이상을 선언하면 64비트 정수
`double`, `currency`, `percent`	숫자 — 넓은 소수(전체 38자리, 소수 10자리)

이 표에서 파생되는 세 가지 규칙은 출력을 기반으로 작업하기 전에 알아 두면 좋습니다.

통화는 통화 유형이 아니라 숫자로 저장됩니다. 실제 조직은 소수 자릿수가 0, 2, 3, 4인 통화 필드를 선언하므로, 모든 숫자 유형은 이를 모두 담을 수 있을 만큼 넓은 하나의 소수 유형으로 저장됩니다. 열에는 통화 기호가 없고 필드별 소수 자릿수 제약도 없습니다. 개체에 CurrencyIsoCode가 있으면 해당 열이 통화 필드 옆에 함께 들어와 금액이 통화를 유지하며, 단일 통화 조직은 개체에 이러한 필드가 없고 임의로 만들어지지도 않습니다.
백분율은 Salesforce가 보고하는 정수 그대로입니다. 20은 0.2가 아니라 20퍼센트를 의미합니다. 가져오는 과정에서 값의 단위가 조정되지 않습니다.
빈 값은 NULL로 저장됩니다. Bulk 결과에서는 실제 null과 명시적인 빈 문자열을 구분할 수 없으므로, 텍스트를 포함한 모든 열에서 둘 다 NULL로 저장됩니다. 빈 문자열 의미를 유지해야 하는 열에는 Salesforce 쪽에 수식 필드가 필요합니다.

단계가 거부하는 필드

일부 Salesforce 필드 유형은 정확하게 저장할 수 없으므로, 필드 선택기는 실행 시점에 실패하는 단계를 저장하게 두는 대신 해당 필드를 사용할 수 없음으로 표시하고 그 이유를 알려 줍니다. 각 거부 메시지에는 필드와 해당 Salesforce 유형이 명시됩니다.

Salesforce 필드 유형	이유	대신 할 일
`address`, `location`(복합 필드)	복합 필드는 Bulk 쿼리에서 직접 읽을 수 있는 값이 없습니다.	구성 요소 필드를 선택하십시오. `BillingStreet`, `BillingCity`, `BillingState`, `BillingPostalCode`, `BillingCountry`와 지리적 위치의 위도 및 경도가 해당합니다. 선택기가 현재 필드의 구성 요소 이름을 알려 줍니다.
`base64`	파일 및 BLOB 콘텐츠는 인라인으로 반환되지 않으며 이 단계가 수행하지 않는 별도의 바이너리 다운로드가 필요합니다.	레코드의 다른 필드를 읽고, 첨부 파일은 별도로 처리하십시오.
`encryptedstring`	Run As 사용자에게 View Encrypted Data 권한이 없으면 Salesforce는 오류 대신 마스킹된 값을 반환하며, 마스킹된 데이터와 실제 데이터를 구분할 방법이 없습니다. 별표로 된 행을 조용히 저장하는 것은 거부하는 것보다 나쁩니다.	데이터를 Salesforce 밖으로 반출해야 하는지 신중하게 판단하십시오. 이 단계로 추출할 수 있는 지원되는 방법은 없습니다.
`anyType`	실제 유형이 행마다 다를 수 있으나 테이블 열에는 유형이 정확히 하나뿐입니다.	유형이 지정된 필드, 또는 값을 텍스트로 표시하는 수식 필드를 추출하십시오.
단계가 인식하지 못하는 모든 유형	값의 의미를 은연중에 바꾸게 되는 텍스트로 저장하지 않고 거부합니다.	해당 유형에 매핑이 추가되도록 지원팀에 문의하십시오.

추출 창은 한 번만 실행됩니다

창 태그는 실행이 불러오는 데이터 창의 이름으로, 기간이나 2026-09 같은 배치 레이블입니다. 워크플로 변수를 사용할 수 있으며, {period} 태그는 단계가 실행될 때마다 해당 변수의 값으로 확인됩니다.

추출 창은 한 번만 실행됩니다. 이미 완료된 창을 다시 실행해도 Salesforce로 돌아가지 않습니다. 단계는 다시 읽지 않았다고 분명하게 알리며, 표시된 행 수가 이전 실행의 것임을 알려 줍니다. 이는 조용한 것이 아니라 눈에 띄는 무동작이며, 이미 저장한 결과 집합의 사본을 다시 페이지 단위로 읽는 일을 막는 동작입니다.

이 단계를 사용하는 방법은 세 가지입니다.

태그를 비워 두고 단계를 일회성 로드로 취급합니다. 첫 번째 실행은 데이터를 읽고, 같은 단계의 두 번째 실행은 이를 재생하며 다시 읽지 않았다고 알립니다. 추출을 만들고 검증할 때, 그리고 한 번만 로드하는 테이블에 사용하십시오.
태그를 입력하고 다음 창을 불러올 때 변경합니다. 2026-09, 그다음 2026-10과 같이 합니다. 태그를 편집하면 새 창이 시작되므로, 사람이 직접 진행하는 월별 로드는 읽히는 그대로 작동합니다.
무인으로 반복되는 가져오기에는 워크플로 변수로 태그를 구성합니다. 예를 들어 워크플로의 앞선 단계가 불러올 기간으로 설정한 {period}가 있습니다. 예약된 각 실행이 자체 창의 이름을 지정하며, 같은 기간 안에서 다시 실행하면 다른 창을 시작하는 대신 해당 창을 재개하거나 재생합니다.

REST API 또는 MCP 호출자는 extract_tag를 직접 전달하며 창마다 고유한 값을 직접 제공합니다.

중단된 실행은 같은 창을 재개하므로, 해당 창이 아직 끝나야 할 수 있는 동안에는 태그를 일정하게 유지하십시오. 태그를 변경하면 새 창과 Salesforce에 대한 새 쿼리가 시작됩니다. 필터나 필드를 변경할 때마다 태그를 변경하십시오. 이미 실행된 태그 아래에서 구성을 편집하면 충돌로 거부됩니다.

Salesforce에서 필터링

개체 전체를 가져온 다음 필터링하지 말고 Salesforce에서 추출 범위를 좁히십시오. 각 필터 항목은 필드, 연산자, 값으로 구성되며 항목은 AND로 결합됩니다. 값에는 {region}과 같은 워크플로 변수를 사용할 수 있습니다.

연산자	참고
`=`, `!=`, `<`, `<=`, `>`, `>=`	입력한 값과 비교합니다.
`LIKE`	와일드카드로 `%`를 사용합니다(예: `Acme%`).
`IN`, `NOT IN`	쉼표로 구분한 값 목록을 지정합니다.

쿼리를 만들기 전에 필드와 연산자 모두 선택한 필드와 대조하여 검사하며 작성할 자유 텍스트 WHERE 절이 없으므로, 필터가 추출 범위를 벗어날 수 없습니다. 선택한 필드로 필터링하십시오. 추출에서 선택하지 않은 필드를 지정한 필터는 거부됩니다.

이 단계는 행 제한과 정렬을 제공하지 않습니다. 쿼리에 둘 중 하나라도 있으면 Bulk API 2.0이 자체 내부 청크 분할을 끄기 때문에 대용량 추출이 더 느려지고 시간 초과가 발생하기 쉬워집니다. 선택적 필터 조건은 쿼리가 너무 크거나 느릴 때 Salesforce가 제시하는 해결책입니다.

데이터 규모와 변동량 적합성

이 방식, 즉 일정에 따라 개체 전체를 읽는 방식은 Account, Opportunity, Lead, Campaign, 그리고 비슷한 규모의 사용자 지정 개체처럼 데이터 규모와 변동량이 중간 정도인 개체에 적합합니다.

Task, EmailMessage 또는 매일 수백만 행이 변하는 대형 사용자 지정 개체와 같이 데이터 규모가 크고 변동량이 많은 개체에는 적합하지 않습니다. 이러한 개체를 매일 밤 전체 가져오기 하면 증분 동기화에는 들지 않을 실제 소요 시간과 API 용량을 소비합니다. 개체는 크지만 일부만 필요하다면, 날짜 범위, 레코드 유형, 소유자와 같이 추출 범위를 제한하는 필터를 사용해 중간 규모의 가져오기로 되돌릴 수 있습니다.

실행이 끝나지 않을 때

표시되는 내용	발생한 상황	조치 사항
15분이 지나도 작업이 계속 실행 중이라는 경고	이 단계는 Salesforce가 쿼리를 마칠 때까지 포그라운드에서 대기하며, 그 대기 시간에는 한도가 있습니다. 백그라운드에서 작업을 진행시키는 것은 없습니다.	단계를 다시 실행하십시오. 동일한 Salesforce 작업에 대한 대기를 재개하며 두 번째 작업을 제출하지 않습니다. 계속 한도를 초과하면 필터 조건으로 추출 범위를 좁히십시오.
창이 이미 완료되어 다시 읽지 않았다는 경고	해당 창이 이전에 실행되었습니다. 표시된 행 수는 이전 실행의 것입니다.	고유한 창 태그로 추출을 실행하거나 태그를 구성하는 변수를 진행시키십시오. 추출 창은 한 번만 실행됩니다를 참조하십시오.
실패하거나 중단된 작업을 명시한 오류	실패한 Bulk 쿼리 작업은 부분 결과를 반환하지 않으며 재개할 수 없습니다. 이제 해당 창은 소진되었습니다.	고유한 창 태그로 다시 실행하십시오. 같은 창을 다시 실행하면 실패가 재생되고 아무것도 제출되지 않으며, 같은 태그에서 단계 구성을 편집하면 충돌로 거부됩니다.
Salesforce의 요청 한도를 명시한 거부	조직의 24시간 롤링 API 요청 허용량이 소진되었습니다. Salesforce는 이에 대한 재시도 대기 시간을 문서화하지 않습니다.	창이 해제될 때까지 기다린 후 다시 실행하십시오. 추출은 여전히 재개할 수 있으며 손실된 것은 없습니다.
필드 하나와 해당 Salesforce 유형을 명시한 거부	해당 필드 유형은 저장할 수 없거나 Run As 사용자가 필드를 읽을 수 없습니다.	단계가 거부하는 필드와 Run As 사용자의 필드 수준 보안을 참조하십시오.

Salesforce는 완료된 쿼리 작업의 결과를 7일 동안 조회할 수 있도록 유지하며, 이것이 중단된 추출을 재개할 수 있게 하는 동시에 결과가 사라지기 전까지 재개를 기다릴 수 있는 기간의 한도이기도 합니다. 작업은 Salesforce의 설정 > 환경 > 작업 > 대량 데이터 로드 작업에서 확인할 수 있습니다.