Salesforce: 개체 쿼리
Salesforce의 Bulk API 2.0으로 표준 또는 사용자 지정 Salesforce 개체 하나를 프로젝트 테이블로 읽습니다. Salesforce 연결, 개체, 필드를 선택하면 단계가 쿼리를 만들고 전체 결과 집합을 페이징하며 각 열을 Salesforce가 선언한 유형으로 적재합니다. 작성할 쿼리는 없습니다.
Salesforce에는 REST API를 통해 클라우드에서 직접 접근하므로 이 단계에는 PlaidLink 에이전트가 필요하지 않습니다.
| 필드 | 필수 | 참고 |
|---|---|---|
| Salesforce 연결 | 예 | 읽을 때 사용할 Salesforce 연결입니다. 연결은 Tools > Connections에서 관리합니다. |
| 환경 | 아니요 | 읽을 연결의 환경입니다. 샌드박스 환경은 샌드박스 조직을, 프로덕션 환경은 프로덕션을 가리키게 하십시오. 프로젝트 환경(기본값)은 프로젝트의 연결 환경을 사용합니다. 고정 환경은 항상 사용자가 선택한 환경을 사용합니다. 단계를 하나의 환경에 고정을 참조하십시오. |
| 개체 | 예 | 개체의 API 이름입니다(Account, Opportunity, Invoice__c). 선택기는 연결의 Run As 사용자가 쿼리할 수 있는 개체를 나열하며 직접 입력한 이름도 허용하므로, 검색을 사용할 수 없는 동안에도 저장된 단계가 계속 작동합니다. |
| 대상 테이블 | 예 | 행이 적재되는 프로젝트 테이블입니다. |
| 삭제되거나 보관된 레코드 포함 | 아니요 | Salesforce queryAll과 마찬가지로 휴지통의 레코드와 보관된 활동도 읽습니다. |
| 필드 | 예 | 추출할 필드를 선택합니다. 최소 하나는 필요합니다. Bulk API 2.0은 개체 전체 선택을 거부하므로 열 목록은 항상 열거되어야 합니다. |
| 필터 | 아니요 | Salesforce에서 추출 범위를 좁힙니다. Salesforce에서 필터링을 참조하십시오. |
| 창 태그 | 아니요 | 추출 창의 이름을 지정합니다. 추출 창은 한 번만 실행됨을 참조하십시오. |
Id는 선택 여부와 관계없이 항상 포함되며, 다시 실행할 때마다 이 키로 병합합니다. 통화 필드는 개체에 CurrencyIsoCode가 있으면 이 필드도 함께 가져옵니다.
미리 보기
섹션 제목: “미리 보기”소스 탭의 미리 보기는 단계를 실행하지 않고 단계가 읽을 내용을 최대 100개 행까지 보여 줍니다. 필터의 변수는 실행할 때와 같은 방식으로 채워지지만 {x:>9} 같은 변수 형식은 지원되지 않습니다. 잠긴 프로젝트에서는 미리 보기를 사용할 수 없습니다. 필터가 미리 보기에서 읽기 전용임을 확인할 수 없는 항목을 사용하면 단계를 실행하라는 안내가 나타납니다.
행이 적재되는 방식
섹션 제목: “행이 적재되는 방식”실행할 때마다 필터에 따라 개체 전체를 읽고 각 페이지를 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에서 필터링”개체 전체를 가져온 다음 필터링하지 말고 Salesforce에서 추출 범위를 좁히십시오. 각 필터 항은 필드, 연산자, 값으로 구성되며 항은 AND로 결합됩니다. 값에는 {region} 같은 워크플로 변수를 사용할 수 있습니다.
| 연산자 | 참고 |
|---|---|
=, !=, <, <=, >, >= |
입력한 그대로의 값과 비교합니다. |
LIKE |
와일드카드로 %를 사용합니다. 예: Acme%. |
IN, NOT IN |
쉼표로 구분한 값 목록을 지정합니다. |
필드와 연산자는 쿼리가 만들어지기 전에 선택한 필드와 대조하여 검사되며, 작성할 자유 텍스트 WHERE 절은 없으므로 필터가 추출 범위를 벗어날 수 없습니다. 선택한 필드로 필터링하십시오. 추출에서 선택하지 않은 필드를 지정한 필터는 거부됩니다.
이 단계는 행 제한과 정렬을 제공하지 않습니다. Bulk API 2.0은 쿼리에 둘 중 하나라도 있으면 자체 내부 청킹을 끄기 때문에, 큰 추출이 더 느려지고 시간 초과가 더 쉽게 발생합니다. 선택적인 필터 조건은 너무 크거나 느린 쿼리에 대한 Salesforce 자체의 해결책입니다.
볼륨과 변동에 대한 적합성
섹션 제목: “볼륨과 변동에 대한 적합성”개체 전체를 일정에 따라 읽는 이 방식은 계정, 영업 기회, 리드, 캠페인 및 비슷한 크기의 사용자 지정 개체처럼 볼륨과 변동이 보통인 개체에 적합합니다.
Task, EmailMessage, 또는 매일 수백만 행이 바뀌는 큰 사용자 지정 개체처럼 볼륨과 변동이 큰 개체에는 맞지 않는 도구입니다. 이러한 개체를 매일 밤 전체 가져오면 증분 동기화에서는 쓰지 않을 경과 시간과 API 용량을 소모합니다. 개체가 크지만 일부만 필요한 경우 추출 범위를 제한하는 필터(날짜 범위, 레코드 유형, 소유자)를 사용하면 볼륨이 보통인 가져오기로 바꿀 수 있습니다.
실행이 끝나지 않는 경우
섹션 제목: “실행이 끝나지 않는 경우”| 표시되는 내용 | 발생한 상황 | 조치 사항 |
|---|---|---|
| 15분이 지나도 작업이 아직 실행 중이라는 오류 | 단계는 포그라운드에서 Salesforce가 쿼리를 완료하기를 기다리며, 이 대기에는 한도가 있습니다. 백그라운드에서 작업을 진행시키는 것은 없습니다. 단계가 실패하므로, 이후 단계가 이 추출이 기록하지 않은 테이블로 실행되지 않습니다. | 워크플로를 재개하거나 단계를 다시 실행하십시오. 동일한 Salesforce 작업에서 대기를 재개하며 두 번째 작업을 제출하지 않습니다. 계속 한도를 초과하면 필터 조건으로 추출 범위를 좁히십시오. |
| 창이 이미 완료되어 다시 읽지 않았다는 경고 | 창이 이전에 실행되었습니다. 표시된 행 수는 이전 실행의 것입니다. | 고유한 창 태그로 추출을 실행하거나 태그를 만드는 데 사용한 변수를 진행시키십시오. 추출 창은 한 번만 실행됨을 참조하십시오. |
| 실패하거나 중단된 작업을 명시하는 오류 | 실패한 Bulk 쿼리 작업은 부분 결과를 제공하지 않으며 재개할 수 없습니다. 이제 해당 창은 소진되었습니다. | 고유한 창 태그로 다시 실행하십시오. 같은 창을 다시 실행하면 실패가 재생되고 아무것도 제출되지 않으며, 같은 태그 아래에서 단계의 구성을 편집하면 충돌로 거부됩니다. |
| Salesforce의 요청 한도를 명시하는 거부 | 조직의 24시간 롤링 API 요청 허용량이 소진되었습니다. Salesforce는 이에 대한 재시도 대기 시간을 문서화하지 않습니다. | 창이 풀릴 때까지 기다린 후 다시 실행하십시오. 추출은 여전히 재개할 수 있으며 손실된 것은 없습니다. |
| 필드 하나와 해당 Salesforce 유형을 명시하는 거부 | 해당 필드 유형을 적재할 수 없거나 Run As 사용자가 필드를 읽을 수 없습니다. | 단계가 거부하는 필드와 Run As 사용자의 필드 수준 보안을 참조하십시오. |
Salesforce는 완료된 쿼리 작업의 결과를 7일 동안 가져올 수 있게 유지하며, 이것이 중단된 추출을 재개할 수 있게 하고 결과가 사라지기 전에 재개가 기다릴 수 있는 시간을 제한합니다. 작업은 Salesforce의 Setup > Environments > Jobs > Bulk Data Load Jobs에서 볼 수 있습니다.
관련 항목
섹션 제목: “관련 항목”- Salesforce 단계
- Salesforce에 연결 — 조직 측 설정을 처음부터 끝까지 안내
- Salesforce REST 커넥터 — 연결 필드 참조
- 워크플로에서 단계 하나 실행