Salesforce Big Objects Implementation Guide

Below you will find brief information for Big Objects. Big Objects let you store and manage massive amounts of data on the Salesforce platform. Big objects capture data for use within Force.com and are accessible via a standard set of APIs to clients and external systems.

PDF

Document

Big Objects Implementation

Guide

Version 41.0, Winter ’18

@salesforcedocs

Last updated: September 21, 2017

Copyright 2000–2017 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc., as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.

CHAPTER 1 Big Objects

In this chapter ...

•

•

•

Big objects let you store and manage massive amounts of data on the Salesforce platform.

Big objects capture data for use within Force.com and are accessible via a standard set of APIs to clients and external systems. What differentiates big objects is that they have been built to provide consistent performance whether there is 1 million records, 100 million, or even 1 billion records. This scale is what gives big objects their power and what defines the features that are provided.

EDITIONS

Available in: Enterprise,

Performance, Unlimited, and Developer Editions

There are two types of big objects.

•

Standard big objects — Objects defined by Salesforce and included in Salesforce products.

FieldHistoryArchive

is a standard big object that stores data as part of the Field Audit Trail product.

•

Custom big objects — New objects that you create to store information unique to your org. Custom big objects extend the functionality that Force.com provides. For example, if you’re building an app to track product inventory, create a custom big object called

HistoricalInventoryLevels to track historical inventory levels for analysis and future optimizations.

Custom Big Object Use Cases

•

360° view of the customer — Extend your Salesforce data model to include detailed information from loyalty programs, e-commerce transactions, billing and provisioning information, and more.

•

Auditing and tracking — Track and maintain a long-term view of your user’s usage of Salesforce or your customer’s usage of your products for analysis or compliance purposes

•

Historical archive — Maintain access to historical data for analysis or compliance purposes while optimizing the performance of your core CRM or Force.com applications.

Considerations

•

Big objects support only object and field permissions.

•

You must use the Metadata API to define a big object or add a field to a custom big object.

•

SOQL relationship queries are based on a lookup field from a big object to a standard or custom object in the select field list (not in filters or subqueries).

•

Big objects support custom Lightning and Visualforce components rather than standard UI elements home pages, detail pages, list views, and so on).

•

You can create up to 100 big object per org. The limits for big object fields are similar to the limits on custom objects, and depend on your org’s license type.

•

Big objects don’t support transactions including both big objects, standard object and custom objects.

Big Objects

•

To support the scale of data in a big object, features like triggers, flows, processes, and Salesforce1, are not available.

Big Objects Define and Deploy Custom Big Objects

Define and Deploy Custom Big Objects

You can define custom big objects with the Metadata API. After you define and deploy a custom big object, you can view it in the Setup UI.

EDITIONS

Define a Custom Big Object

Available in: Enterprise,

Performance, Unlimited, and Developer Editions

To use file-based Metadata API calls, define a custom big object by creating XML files that contain the definition, fields, and composite primary key (index) for the custom big object.

You define a custom big object by creating an XML file that contains its definition, fields, and index.

•

object

files—Create a file for each object to define the custom big object, it’s fields and it’s index.

•

permissionSet

/ profile

files—Create a permissionSet or profile file to specify permissions for each field. These files are not required, but is required to grant access to users. By default, access to a custom big object is restricted.

•

package

file—Create a file for the metadata package to specify the contents.

Note: While custom big objects use the “CustomObject” metadata type, some parameters are unique to big objects and others are not applicable. The specific metadata parameters that apply to big objects are outlined in this document.

Naming Conventions for Custom Big Objects

Object names must be unique across all standard objects, custom objects, external objects, and big objects in the org. In the API, the names of custom big objects are identified by a suffix of two underscores immediately followed by a lowercase “b” (__b). For example, an external object named “HistoricalInventoryLevels” is seen as HistoricalInventoryLevels__b in that organization's WSDL. We recommend that you make object labels unique across all objects in the org - standard, custom, external and big objects.

CustomObject Metadata

Field Name

deploymentStatus fields fullName indexes label pluralLabel

Field Type

CustomField[]

Description

DeploymentStatus

( enumeration of type string)

Custom big object’s deployment status (

Deployed

for all big objects)

Definition of a field in the object string

Index[] string string

Unique API name of a field

Definition of the index

Object’s name as displayed in the UI

Field plural name as displayed in the UI

CustomField Metadata

Field Name

fullName

Field Type

string

Description

Unique API name of a field.

Big Objects

Field Name

label length pluralLabel precision

Field Type

string int string int referenceTo relationshipName required string string boolean scale type int

FieldType

Define and Deploy Custom Big Objects

Description

Field name as displayed in the UI.

Length of a field in characters (Text and LongTextArea fields only).

Field plural name as displayed in the UI.

Number of digits for a number value. For example, the number 256.99 has a precision of 5 (number fields only).

Related object type for a lookup field (lookup fields only).

Name of a relationship as displayed in the UI (lookup fields only).

Specifies whether the field is required. All fields that are part of the index must be marked as required.

Number of digits to the right of the decimal point for a number value. For example, the number 256.99 has a scale of 2 (number fields only).

Field type. Supports DateTime, Lookup, Number, Text, and LongTextArea.

Note: Uniqueness is not supported for custom fields.

Index Metadata

Represents an index defined within a custom big object

. Use this metadata type to define the composite primary key (index) for a custom big object.

Field Name

fields

Field Type

IndexField[]

Description

The definition of the fields in the index.

IndexField Metadata

Defines which fields make up the index, their order, and sort direction. The order in which the fields are defined determines the order fields are listed in the index.

Field Name

name sortDirection

Field Type

string string

Description

Required. The API name for the field that’s part of the index. This value must match the value of the fullName

value for the field in the fields section and be marked as required.

Required. The sort direction of the field in the index. Valid values are

ASC

for ascending order and

DESC

for descending order.

Big Objects Define and Deploy Custom Big Objects

Example:

Create Metadata Files for Deployment

The following XML excerpts create metadata files that you can deploy as a package. Each Customer Interaction object represents customer data from a single session in an online video game. The index is defined by the

Account__c

Game_Platform__c

, and

Play_Date__c

fields, and a lookup field relates the Customer Interactions to the Account object.

Customer_Interaction__b.object

<?xml version="1.0" encoding="UTF-8"?>

<deploymentStatus>Deployed</deploymentStatus>

<fullName>In_Game_Purchase__c</fullName>

<label>In-Game Purchase</label>

<required>false</required>

<unique>false</unique>

</fields>

<fullName>Level_Achieved__c</fullName>

<label>Level Achieved</label>

<required>false</required>

<unique>false</unique>

</fields>

<fullName>Lives_This_Game__c</fullName>

<label>Lives Used This Game</label>

<required>false</required>

<unique>false</unique>

</fields>

<fullName>Game_Platform__c</fullName>

<label>Platform</label>

<unique>false</unique>

</fields>

<fullName>Score_This_Game__c</fullName>

<label>Score This Game</label>

<required>false</required>

<unique>false</unique>

Big Objects Define and Deploy Custom Big Objects

</fields>

<fullName>Account__c</fullName>

<label>User Account</label>

<referenceTo>Account</referenceTo>

<relationshipName>Game_User_Account</relationshipName>

<type>Lookup</type>

</fields>

<type>DateTime</type>

</fields>

<fullName>Play_Duration__c</fullName>

<label>Play Duration</label>

<required>false</required>

<type>Number</type>

</fields>

<fullName>CustomerInteractionsIndex</fullName>

<label>Customer Interactions Index</label>

<name>Account__c</name>

</fields>

<name>Game_Platform__c</name>

</fields>

</fields>

</indexes>

<label>Customer Interaction</label>

<pluralLabel>Customer Interactions</pluralLabel>

</CustomObject>

package.xml

<?xml version="1.0" encoding="UTF-8"?>

<types>

<name>CustomObject</name>

Big Objects Define and Deploy Custom Big Objects

</types>

<types>

<name>PermissionSet</name>

</types>

</Package>

Customer_Interaction_BigObject.PermissionSet

<?xml version="1.0" encoding="UTF-8"?>

<field>Customer_Interaction__b.In_Game_Purchase__c</field>

</fieldPermissions>

<field>Customer_Interaction__b.Level_Achieved__c</field>

</fieldPermissions>

<field>Customer_Interaction__b.Lives_This_Game__c</field>

</fieldPermissions>

<field>Customer_Interaction__b.Play_Duration__c</field>

</fieldPermissions>

<field>Customer_Interaction__b.Score_This_Game__c</field>

</fieldPermissions>

</PermissionSet>

Deploy Custom Big Objects as a Metadata Package

Use the Metadata API to deploy a custom big object. You can use several different tools, like Workbench or the Ant Migration Tool, to deploy.

Big Objects Define and Deploy Custom Big Objects

Note: You can run a test deployment by using the checkOnly

deployment option. In Workbench, select the Check Only option on the Deploy screen.

View a Custom Big Object in Setup

After you’ve deployed your custom big object, you can view it by logging in to your organization and, from Setup, entering

Big

Objects

in the

Quick Find

box, then selecting Big Objects.

Click the name of a big object, to see its fields and relationships.

Big Objects Populate a Custom Big Object

Populate a Custom Big Object

Use Salesforce APIs to populate a custom big object.

You can use a CSV file to load data into a custom big object via SOAP API Bulk API. The first row in the CSV file must contain the field labels used to map the CSV data to the fields in the custom big object during import.

Re-inserting a record with the same index but different data results in behavior similar to an upsert operation. If a record with the index exists, the insert overwrites the index values with the new data. Insertion is idempotent, so inserting data that already exists won't result in duplicates. Reinserting is helpful when uploading millions of records. If an error occurs, the reinsert reuploads the failed uploads without duplicate data. During the reinsertion, if no record exists for the provided index, a new record is inserted.

For example, this CSV file contains data for import into a Customer Interaction big object.

Play Start,In-Game Purchase,Level Achieved,Lives Used,Platform,Play Stop,Score,Account

2015-01-01T23:01:01Z,A12569,57,7,PC,2015-01-02T02:27:01Z,55736,001R000000302D3

2015-01-03T13:22:01Z,B78945,58,7,PC,2015-01-03T15:47:01Z,61209,001R000000302D3

2015-01-04T15:16:01Z,D12156,43,5,iOS,2015-01-04T16:55:01Z,36148,001R000000302D3

Populate a Custom Big Object with Apex

Use Apex to populate a custom big object.

Big Objects Populate a Custom Big Object with Apex

Populate a Custom Big Object with Apex

Use Apex to populate a custom big object.

You can create and update custom big object records in Apex using the insertImmediate

method.

Warning:

Any Apex tests that use DML calls will fail and potentially insert bad data into the target big object. This data won’t be deletable. To test DML calls, use a mocking framework with the Apex stub API to contain calls to the target big object.

Here is an example of an insert operation in Apex that assumes a table in which the index consists of

FirstName__c

LastName__c

, and

Address__c

<PhoneBook__b> pb = new PhoneBook__b(); pb.FirstName__c = "John"; pb.LastName__c = "Smith"; pb.Address__c = "1 Market St"; pb.PhoneNumber__c = "555-1212";

database.insertImmediate(pb);

pb.Address__c = "1 Market St, San Francisco, CA";

database.insertImmediate(pb);

pb.PhoneNumber__c = "800-555-1212";

database.insertImmediate(pb);

SOQL with Big Objects

You can query the fields in a big object’s index using a subset of standard SOQL commands.

Build an index query starting from the first field defined in the index, without gaps between the first and last field in the query. You can use

, or

. on the last field in your query. Any prior fields in your query can only use the

operator. The

NOT IN

EXCLUDES

, and

INCLUDES

operators are not valid in any query.

The following queries assume that you have a table in which the index is defined by

LastName__c

FirstName__c

, and

PhoneNumber__c

This query specifies all three fields in the index. In this case, the filter on

PhoneNumber__c

can be a range.

SELECT LastName__c, FirstName__c, PhoneNumber__c

FROM Phone_Book__b

WHERE LastName__c='Kelly' AND FirstName__c='Charlie' AND PhoneNumber__c='2155555555'

Big Objects

This query specifies only the first two fields in the index. In this case, the filter on

FirstName__c

can be a range.

SELECT LastName__c, FirstName__c, PhoneNumber__c

FROM Phone_Book__b

WHERE LastName__c='Kelly' AND FirstName__c='Charlie'

This query specifies only the first field in the index. The filter on

LastName__c

can be a range.

SELECT LastName__c, FirstName__c, PhoneNumber__c

FROM Phone_Book__b

WHERE LastName__c='Kelly'

This query doesn’t work because of a gap in the query where

FirstName__c

is required.

SELECT LastName__c, FirstName__c, PhoneNumber__c

FROM Phone_Book__b

WHERE LastName__c='Kelly' AND PhoneNumber__c='2155555555'

Note:

These restrictions do not apply to Async SOQL queries against big objects.

SOQL with Big Objects

CHAPTER 2 Async SOQL

In this chapter ...

•

•

•

Async SOQL is a method for running SOQL queries when you can’t wait for the results in real time. These queries are run in the background over Salesforce entity data, standard objects, custom objects, and big objects. It provides a convenient way to query large amounts of data stored in Salesforce.

EDITIONS

Available in: Enterprise,

Performance, Unlimited, and Developer Editions

Async SOQL is implemented as a RESTful API that enables you to run queries in the familiar syntax of SOQL. Because of its asynchronous operation, you can subset, join, and create more complex queries and not be subject to timeout limits. This situation is ideal when you have millions or billions of records and need more performant processing than is possible using synchronous SOQL. The results of each query are deposited into an object you specify, which can be a standard object, custom object, or big object.

Note: Async SOQL for standard and custom objects is in Pilot.

You can run multiple queries in the background and monitor their completion status. The limit for Async

SOQL queries is two concurrent queries, and a maximum of 10 in a 24-hour period.

Async SOQL Versus SOQL

SOQL and Async SOQL provide many of the same capabilities. So when would you use an Async SOQL query instead of standard SOQL?

Use standard SOQL when:

•

You want to display the results in the UI without having the user wait for results.

•

You want results returned immediately for manipulation within a block of Apex code.

•

You know that the query will return a small amount of data.

Use Async SOQL when:

•

You are querying against millions of records.

•

You want to ensure that your query completes.

•

You do not need to do aggregate queries or filtering outside of the index.

Async SOQL

For example, let’s say that you want to analyze the years and years of opportunity history collected by

Salesforce. The results could help you identify which current and future opportunities are more likely to close and give you a better picture of your forecast. But because the opportunity history data is stored with all the field history data across the application, the volume of data is too large to query directly.

That’s where Async SOQL comes in! You can use it to write a query that extracts a smaller, representative subset of the data that you’re interested. You can store this working dataset in a custom object and use it in reports, dashboards, or any other Force.com feature.

With big objects, you can now bring a much finer level of detail into your applications using data that you already have. For example, every interaction an individual has with your marketing campaign is stored as data that you can use, but it’s unwieldy in its raw form. With Async SOQL, you can aggregate that data by campaign and day, allowing you to extract the relevant details of the full dataset into a

Async SOQL smaller, usable dataset. As in the previous example, the smaller working set can live in a custom object and be used in your reports and dashboards.

Async SOQL Running Async SOQL Queries

Running Async SOQL Queries

Learn how to run Async SOQL queries on your objects and check on the status of your query using the Chatter REST API.

Formulating Your Async SOQL Query

To use Async SOQL effectively, it’s helpful to understand its key component and other related concepts. Each query is formulated in the

POST request as a JSON-encoded list of three or four key-value pairs.

Request body for POST

Name Type

query operation

String

String targetObject

String targetFieldMap

Map<String,

String>

Description Required or

Optional

Required Specifies the parameters for the SOQL query you want to execute.

Specify whether the query is an insert or upsert. If the record doesn’t exist, an upsert behaves like an insert.

Optional

Note: Upsert is not supported for big objects

A standard object, custom object, external object, or big object into which to insert the results of the query.

Required

Defines how to map the fields in the query result to the fields in the target object.

Required

Note: When defining the targetFieldMap

parameter, make sure that the field type mappings are consistent. If the source and target fields don’t match, these considerations apply.

•

Any source field can be mapped onto a target text field.

•

If the source and target fields are both numerical, the target field must have the same or greater number of decimal places than the source field. If not, the request fails. This behavior is to ensure that no data is lost in the conversion.

•

If a field in the query result is mapped more than once, even if mapped to different fields in the target object, only the last mapping is used.

Available

Version

35.0

39.0

35.0

Async SOQL Running Async SOQL Queries

Name Type

targetValueMap

Map<String,

String> targetExternalIdField

String

Description Required or

Optional

Defines how to map static strings to fields in the target object. Any field or alias can be used as the

TargetValueMap

value in the SELECT clause of a query.

You can map the special value, $JOB_ID, to a field in the target object. The target field must be a lookup to the Background Operation standard object. In this case, the ID of the Background

Operation object representing the Async SOQL query is inserted. If the target field is a text field, it must be at least 15–18 characters long.

Optional

You can also include any field or alias in the SELECT clause of the

TargetValueMap

. They can be combined together to concatenate a value to be used.

The ID of the target sObject. Required for upsert operations.

Optional

Available

Version

37.0

39.0

This simple Async SOQL example queries

SourceObject__c

, a source custom object, and directs the result to

TargetObject__c

, another custom object. You can easily map the fields in the source object to the fields of the target object in which you want to write the results.

Example URI

https://yourInstance.salesforce.com/services/data/v38.0/async-queries/

Example POST request body

{

"query": "SELECT firstField__c, secondField__c FROM SourceObject__c",

"operation": "insert",

"targetObject": "TargetObject__c",

"targetFieldMap": {"firstField__c":"firstFieldTarget__c",

"secondField__c":"secondFieldTarget__c"

"targetValueMap": {"$JOB_ID":"BackgroundOperationLookup__c",

"Copy fields from source to target":"BackgroundOperationDescription__c"

}

The response of an Async SOQL query includes the elements of the initial POST request.

Response body for POST

Async SOQL Running Async SOQL Queries

Property Name

jobId message operation

Type

String

Description Filter Group and

Version

The ID of the Async SOQL query. This ID corresponds to an entry in the Background

Operation standard object. It matches the

ID that is used in the targetValueMap when $JOB_ID is used. To get the status of an async query job, use this ID in an Async

Query, Status request

(

/async-queries/

jobId

Big, 35.0

Available Version

35.0

A text message that provides information regarding the query, such as an error message if the query failed.

Big, 37.0

Specify whether the query is an insert or upsert. If the record doesn’t exist, an upsert behaves like an insert.

Big, 39.0

Note: Upsert is not supported for big objects

37.0

.39.0

35.0

query status

String

Specifies the parameters for the SOQL query you want to execute.

Big, 35.0

Status of an async query job.

•

Canceled

—The job was canceled before it could be run.

•

Success

—The job was successfully completed.

•

Failed

—The job failed after the system submitted it or because the request exceeded the Async SOQL limits. The message field provides details on the reason for failure.

•

Running

—The job is running successfully, and the org hasn’t exceeded any limits.

•

Scheduled

—The new job has been created and scheduled, but is not yet running.

Big, 35.0

targetExternalIdField

String The ID of the target sObject. Required for upsert operations.

Big, 39.0

targetFieldMap

Map<String, String> Defines how to map the fields in the query result to the fields in the target object.

Big, 35.0

Note: When defining the targetFieldMap

parameter,

35.0

39.0

35.0

Async SOQL Running Async SOQL Queries

Property Name Type Description Filter Group and

Version

Available Version

make sure that the field type mappings are consistent. If the source and target fields don’t match, these considerations apply.

•

Any source field can be mapped onto a target text field.

•

If a field in the query result is mapped more than once, even if mapped to different fields in the target object, only the last mapping is used.

targetValueMap

Map<String, String> Defines how to map static strings to fields in the target object. Any field or alias can be used as the

TargetValueMap

value in the SELECT clause of a query.

Big, 37.0

You can map the special value, $JOB_ID, to a field in the target object. The target field must be a lookup to the Background

Operation standard object. In this case, the

ID of the Background Operation object representing the Async SOQL query is inserted. If the target field is a text field, it must be at least 15–18 characters long.

You can also include any field or alias in the

SELECT clause of the

TargetValueMap

They can be combined together to concatenate a value to be used.

targetObject

String A standard object, custom object, external object, or big object into which to insert the results of the query.

Big, 35.0

37.0

35.0

Async SOQL Running Async SOQL Queries

Example POST response body

{

"jobId": "08PD000000003kiT",

"message": "",

"query": "SELECT firstField__c, secondField__c FROM SourceObject__c",

"status": "New",

"targetObject": "TargetObject__c",

"targetFieldMap": {"firstField__c":"firstFieldTarget__c",

"secondField__c":"secondFieldTarget__c"

"targetValueMap": {"$JOB_ID":"BackgroundOperationLookup__c",

"Copy fields from source to target":"BackgroundOperationDescription__c"

}

Tracking the Status of Your Query

To track the status of a query, specify its jobID with an HTTP GET request.

https://yourInstance.salesforce.com/services/data/v38.0/async-queries/<jobID>

The response is similar to the initial POST response but with updated status and message fields to reflect the status.

Example GET response body

{

"jobId": "08PD000000000001",

"message": "",

"query": "SELECT firstField__c, secondField__c FROM SourceObject__c",

"status": "Complete",

"targetObject": "TargetObject__c",

"targetFieldMap": {"firstField__c":"firstFieldTarget__c",

"secondField__c":"secondFieldTarget__c" }

}

You can get status information for all queries with the following HTTP GET request.

https://yourInstance.salesforce.com/services/data/v38.0/async-queries/

Example GET response body

{

"asyncQueries" : [ {

"jobId" : "08PD00000000002",

"message" : "",

"query" : "SELECT String__c FROM test__b",

"status" : "Running",

Async SOQL Async SOQL Use Cases

"targetFieldMap" : {

"String__c" : "String__c"

"targetObject" : "test__b",

"targetValueMap" : { }

}, {

"jobId": "08PD000000000001",

"message": "Complete",

"query": "SELECT firstField__c, secondField__c FROM SourceObject__c",

"status": "Complete",

"targetObject": "TargetObject__c",

}

"targetFieldMap": {"firstField__c":"firstFieldTarget__c",

"secondField__c":"secondFieldTarget__c" }

Canceling a Query

You can cancel a query using an HTTP DELETE request by specifying its jobId.

https://yourInstance.salesforce.com/services/data/v38.0/async-queries/jobId

Note: Canceling a query that has already completed has no effect.

Handling Errors in Async SOQL Queries

Two different types of errors can occur during the execution of an Async SOQL query.

•

An error in the query execution

•

One or more errors writing the results into the target object

Problems in executing the job cause some errors. For example, an invalid query was submitted, one of the Async SOQL limits was exceeded, or the query caused a problem with the underlying infrastructure. For these errors, the response body includes a status of

Failed. The message parameter provides more information on the cause of the failure.

Other times, the query executes successfully but encounters an error while attempting to write the results to the target object. Because of the volume of data involved, capturing every error is inefficient. Instead, subsets of the errors generated are captured and made available. Those errors are captured in the BackgroundOperationResult object and retained for seven days. You can query this object with the Async SOQL query jobID to filter the errors for the specific Async SOQL query. Async SOQL job info is retained for a year.

Async SOQL Use Cases

Understand some of the common Async SOQL use cases.

Customer 360 Degree and Filtering

In this use case, administrators load various customer engagement data from external sources into Salesforce big objects and then process the data to enrich customer profiles in Salesforce. The goal is to store customer transactions and interactions, such as point-of-sale data, orders, and line items in big objects and then process and correlate that data with your core CRM data. Anchoring customer

Async SOQL Async SOQL Use Cases transactions and interactions with core master data provides a richer 360-degree view that translates into an enhanced customer experience.

The following example analyzes the customer data stored in the Rider record of a car-sharing service. The source big object, Rider_Record_b, has a lookup relationship with the Contact object, allowing for an enriched view of the contact’s riding history. You can see that the query includes Rider__r.FirstName, Rider__r.LastName, Rider__r.Email as part of the

SELECT

clause. This example demonstrates the ability to join big object data (Rider_Record__b) with Contact data (FirstName, LastName, Email) in a single Async SOQL query.

Example URI

https://yourInstance—api.salesforce.com/services/data/v38.0/async-queries/

Example POST request body

{

"query": "SELECT End_Location_Lat__c, End_Location_Lon__c, End_Time__c,

Start_Location_Lat__c, Start_Location_Lon__c, Start_Time__c,

Car_Type__c, Rider__r.FirstName, Rider__r.LastName,

Rider__r.Email

FROM Rider_Record__b WHERE Star_Rating__c = '5'",

"targetObject": "Rider_Reduced__b",

"targetFieldMap": {"End_Location_Lat__c":"End_Lat__c",

"End_Location_Lon__c":"End_Long__c",

"Start_Location_Lat__c": "Start_Lat__c",

"Start_Location_Lon__c": "Start_Long__c",

"End_Time__c": "End_Time__c",

"Start_Time__c": "Start_Time__c",

"Car_Type__c": "Car_Type__c",

"Rider__r.FirstName": "First_Name__c",

}

"Rider__r.LastName": "Last_Name__c",

"Rider__r.Email": "Rider_Email__c"

}

Example POST response body

{

"jobId": "08PB000000000NA",

"message": "",

"query": "SELECT End_Location_Lat__c, End_Location_Lon__c, End_Time__c,

Start_Location_Lat__c, Start_Location_Lon__c, Start_Time__c,

Car_Type__c, Rider__r.FirstName, Rider__r.LastName,

Rider__r.Email

FROM Rider_Record__b WHERE Star_Rating__c = '5'",

"status": "New",

"targetFieldMap": {"End_Location_Lat__c":"End_Lat__c",

"End_Location_Lon__c":"End_Long__c",

"Start_Location_Lat__c": "Start_Lat__c",

"Start_Location_Lon__c": "Start_Long__c",

"End_Time__c": "End_Time__c",

Async SOQL Async SOQL Use Cases

}

"Start_Time__c": "Start_Time__c",

"Car_Type__c": "Car_Type__c",

"Rider__r.FirstName": "First_Name__c",

"Rider__r.LastName": "Last_Name__c",

"Rider__r.Email": "Rider_Email__c"

"targetObject": "Rider_Reduced__b"

Field Audit Trail

Field Audit Trail lets you define a policy to retain archived field history data up to 10 years, independent of field history tracking. This feature helps you comply with industry regulations related to audit capability and data retention.

You define a Field Audit Trail policy using the

HistoryRetentionPolicy

object for each object you want to archive. The field history data for that object is then moved from the History related list into the

FieldHistoryArchive

object at periodic intervals, as specified by the policy. For more information, see the Field Audit Trail Implementation Guide .

You can use Async SOQL to query archived fields stored in the

FieldHistoryArchive

object. You can use the

WHERE

clause to filter the query by specifying comparison expressions for the

FieldHistoryType

ParentId

, and

CreatedDate

fields, as long as you specify them in that order.

This example queries archived accounts created within the last month.

Example URI

https://yourInstance.salesforce.com/services/data/v38.0/async-queries/

Example POST request body

{

"query": "SELECT ParentId, FieldHistoryType, Field, Id, NewValue, OldValue

FROM FieldHistoryArchive WHERE FieldHistoryType = ‘Account’

AND CreatedDate > LAST_MONTH”,

"targetObject": "ArchivedAccounts__b",

"targetFieldMap": {"ParentId": "ParentId__c",

"FieldHistoryType": "FieldHistoryType__c",

"Field": "Field__c",

"Id": "Id__c",

"NewValue": "NewValue__c",

}

"OldValue": "OldValue__c"

}

Example POST response body

{

"jobId": "07PB000000006PN",

"message": "",

"query": "SELECT ParentId, FieldHistoryType, Field, Id, NewValue, OldValue

FROM FieldHistoryArchive WHERE FieldHistoryType = ‘Account’ AND CreatedDate

> LAST_MONTH”,

Async SOQL Async SOQL Use Cases

"status": "New",

"targetObject": "ArchivedAccounts__b",

"targetFieldMap": {"ParentId": "ParentId__c",

"targetObject": "Rider_Reduced__b" }

}

Note: All number fields returned from a SOQL query of archived objects are in standard notation, not scientific notation, as in the number fields in the entity history of standard objects.

Event Monitoring

Login Forensics and Data Leakage Detection, currently in pilot, enable you to track who is accessing confidential and sensitive data in your Salesforce org. You can view information about individual events or track trends in events to swiftly identify unusual behavior and safeguard your company’s data. This feature is useful for compliance with regulatory and audit requirements.

Note: These features are available to select customers through a pilot program. To be nominated to join this pilot program, contact salesforce.com.

In the current pilot, you can monitor data accessed through API calls, which covers many common scenarios because more than 50% of SOQL queries occur using the SOAP, REST, or Bulk APIs. Key information about each query, such as the Username, UserId, UserAgent, and SourceIP, is stored in the ApiEvent object. You can then run SOQL queries on this object to find out details of user activity in your org.

For example, let’s say you want to know everyone who viewed the contact record of your company’s CEO, Jane Doe. The key to this query is the CEO’s contact record ID: 003D000000QYVZ5. (You can also query the ID using SOQL:

SELECT Id FROM Contact

WHERE Name = 'Jane Doe'

). You can use the following Async SOQL query to determine all users who saw their contact information, including when, how, and where they saw it.

Example URI

https://yourInstance—api.salesforce.com/services/data/v38.0/async-queries/

Example POST request body

{

"query": "SELECT Soql, SourceIp, Username, EventTime FROM ApiEvent

WHERE RecordInfo Like '%003D000000QYVZ5%'",

"targetObject": "QueryEvents__c",

"targetFieldMap": {"Soql":"QueryString__c","SourceIp":"IPAddress__c",

"Username":"User__c", "EventTime":"EventTime__c",

"UserAgent":"UserAgent__c"

}

Example POST response body

{

"jobId": "05PB000000001PQ",

"message": "",

"query": "SELECT Soql, SourceIp, Username, EventTime

FROM ApiEvent WHERE RecordInfo Like '%003D000000QYVZ5%'",

Async SOQL Async SOQL Use Cases

"status": "Complete",

"targetObject": "QueryEvents__c",

"targetFieldMap": {"Soql":"QueryString__c","SourceIp":"IPAddress__c",

"Username":"User__c", "EventTime":"EventTime__c", "UserAgent":"UserAgent__c"

}

Note: All number fields returned from a SOQL query of archived objects are in standard notation, not scientific notation, as in the number fields in the entity history of standard objects.

If you ask this question on a repeated basis for audit purposes, you can automate the query using a cURL script.

curl -H "Content-Type: application/json" -X POST -d

'{"query": "SELECT Soql, SourceIp, UserAgent, Username, EventTime FROM ApiEvent WHERE

RecordInfo Like'%003D000000QYVZ5%'","targetObject": "QueryEvents__c",

"targetFieldMap": {"Soql":"QueryString__c", "SourceIp":"IPAddress__c", "Username":"User__c",

"EventTime":"EventTime__c",UserAgent}}'

"https://

yourInstance

.salesforce.com/services/data/v35.0/async-queries" -H

"Authorization: Bearer 00D30000000V88A!ARYAQCZOCeABy29c3dNxRVtv433znH15gLWhLOUv7DVu.

uAGFhW9WMtGXCul6q.4xVQymfh4Cjxw4APbazT8bnIfxlRvUjDg"

Another event monitoring use case is to identify all users who accessed a sensitive field, such as Social Security Number or Email. For example, you can use the following Async SOQL query to determine the users who saw social security numbers and the records in which those numbers were exposed.

Example URI

https://yourInstance—api.salesforce.com/services/data/v38.0/async-queries/

Example POST request body

{

"query": "SELECT Soql, Username, RecordIds, EventTime FROM ApiEvent

WHERE Soql Like '%SSN__c%'",

"targetObject": "QueryEvents__c",

"targetFieldMap": {"Soql":"QueryString__c", "Username":"User__c",

}

"EventTime":"EventTime__c", "RecordIds":"Records_Seen__c"

}

Example POST response body

{

"jobId": "08PB000000001RS",

"message": "",

"query": "SELECT Soql, Username, RecordIds, EventTime FROM ApiEvent

WHERE Soql Like '%SSN__c%'",

"status": "Complete",

"targetFieldMap": {"Soql":"QueryString__c", "Username":"User__c",

Async SOQL Supported SOQL Commands

"EventTime":"EventTime__c", "RecordIds":"Records_Seen__c"

}

"targetObject": "QueryEvents__c"

Supported SOQL Commands

Async SOQL supports a subset of commands in the SOQL language. The subset includes the most common commands that are relevant to key use cases.

Note:

For details of any command, refer to the SOQL documentation .

WHERE

Comparison operators

=, !=, <, <=, >, >=, LIKE

Logical operators

AND, OR

Date formats

YYYY-MM-DD, YYYY-MM-DDThh:mm:ss-hh:mm

Example

SELECT AnnualRevenue

FROM Account

WHERE NumberOfEmployees > 1000 AND ShippingState = ‘CA’

Date Functions

Date functions in Async SOQL queries allow you to group or filter data by time periods, such as day or hour.

Method

DAY_ONLY()

HOUR_IN_DAY()

CALENDAR_MONTH()

CALENDAR_YEAR()

Details

Returns a date representing the day portion of a dateTime field.

Returns a number representing the hour in the day for a dateTime field.

Returns a number representing the month for a dateTime field.

Returns the year for a dateTime field.

Example

SELECT DAY_ONLY(date__c), HOUR_IN_DAY(date__c), count(Id)

FROM FieldHistoryArchive

GROUP BY DAY_ONLY(date__c), HOUR_IN_DAY(date__c)

Async SOQL Supported SOQL Commands

Aggregate Functions

AVG(field), COUNT(field), COUNT_DISTINCT(field), SUM(field), MIN(field), MAX(field)

Note:

MIN()

and

MAX()

do not support picklists.

Example

SELECT COUNT(Id)

FROM FieldHistoryArchive

HAVING

Use this command to filter results from aggregate functions.

Example

SELECT LeadSource, COUNT(Name)

FROM Lead

GROUP BY LeadSource HAVING COUNT (Name) > 100

GROUP BY

Use this option to avoid iterating through individual query results. Specify a group of records instead of processing many individual records.

Example

SELECT COUNT(Id) count, CreatedById createdBy

FROM FieldHistoryArchive

GROUP BY CreatedById

Relationship Queries

Single-level child-to-parent relationships are supported using dot notation. Use these queries with the SELECT, WHERE, and GROUP BY clauses.

Example

SELECT Account.ShippingState s, COUNT(Id) c

FROM Contac

GROUP BY Account.ShippingState

Using Aliases with Aggregates

Examples

{"query":"SELECT count(Id) c, EventTime t FROM LoginEvent group by EventTime",

"targetObject":"QueryEvents__c",

Async SOQL

}

"targetFieldMap":{"c":"Count__c", "t" : "EventTime__c"}

{"query":"SELECT count(Id), EventTime FROM LoginEvent group by EventTime",

"targetObject":"QueryEvents__c",

}

"targetFieldMap":{"expr0":"Count__c","EventTime" : "EventTime__c"}

{"query":"SELECT count(Id ) c , firstField__c f FROM SourceObject__c",

}

"targetObject":"TargetObject__c",

"targetFieldMap":{"c":"countTarget__c","f":"secondFieldTarget__c"}

Supported SOQL Commands

INDEX

Async SOQL

Aggregate Functions

Aliases

Commands

Overview

Queries

Use cases

Big Objects

Apex

Composite primary key

Custom Big Object

Defining

Deploying

Index

Overview

Populating

9–10

Querying

Hello! I am an AI chatbot specifically trained to assist you with the salesforce Big Objects Implementation Guide. I have thoroughly reviewed the document and can help you locate the exact information you need or explain the content in clear and simple terms. Whether you’re looking for guidance on specific features, troubleshooting steps, or general usage, feel free to ask your questions. The more details you provide about your concerns or needs, the more accurately and effectively I can assist you!

Show related prompts

Assistant typing

Assistant is out of keyboard. Please, try again later.

Key features

Store and manage massive amounts of data
Consistent performance regardless of data volume
Enable 360° view of the customer
Support auditing and tracking
Maintain access to historical data
Define and deploy using Metadata API
Populate using Salesforce APIs or Apex

Frequently asked questions

Big Objects are a Salesforce feature designed to store and manage massive amounts of data, providing consistent performance even with billions of records. They're suitable for scenarios requiring a comprehensive view of customers, detailed historical data, and efficient data analysis.

You use the Metadata API to define a custom Big Object. This involves creating XML files containing the object's definition, fields, and index. After creating the files, you deploy them using tools like Workbench or Ant Migration Tool.

Big Objects can be used for various purposes, including creating a 360-degree view of your customers by integrating data from different sources, tracking historical data for analysis or compliance, and maintaining a long-term view of user activity for auditing purposes.