SObject Class

Contains methods for the sObject data type.

System

SObject methods are all instance methods: they are called by and operate on an sObject instance such as an account or contact. The following are the instance methods for sObjects.

For more information on sObjects, see Working with sObjects.

The following are methods for SObject. All are instance methods.

• addError(errorMsg)

  Marks a trigger record with a custom error message and prevents any DML operation from occurring.

• addError(errorMsg, escape)

  Marks a trigger record with a custom error message, specifies if the error message should be escaped, and prevents any DML operation from occurring.

• addError(exceptionError)

  Marks a trigger record with a custom error message and prevents any DML operation from occurring.

• addError(exceptionError, escape)

  Marks a trigger record with a custom exception error message, specifies whether or not the exception error message should be escaped, and prevents any DML operation from occurring.

• addError(fieldName, errorMsg)

  Dynamically add errors to fields of an SObject associated with the specified field name.

• addError(fieldToken, errorMsg)

  Dynamically add errors to an SObject instance associated with the specified field.

• addError(fieldName, errorMsg, escape)

  Dynamically add errors to fields of an SObject associated with the specified field name.

• addError(fieldToken, errorMsg, escape)

  Dynamically add errors to an SObject instance associated with the specified field.

• clear()

  Clears all field values

• clone(preserveId)

  Creates a copy of the SObject record.

• clone(preserveId, isDeepClone)

  Creates a copy of the SObject record.

• clone(preserveId, isDeepClone, preserveReadonlyTimestamps)

  Creates a copy of the SObject record.

• clone(preserveId, isDeepClone, preserveReadonlyTimestamps, preserveAutonumber)

  Creates a copy of the SObject record.

• get(fieldName)

  Returns the value for the field specified by fieldName, such as AccountNumber.

• get(field)

  Returns the value for the field specified by the field token Schema.sObjectField, such as Schema.Account.AccountNumber.

• getCloneSourceId()

  Returns the ID of the entity from which an object was cloned. You can use it for objects cloned through the Salesforce user interface. You can also use it for objects created using the System.SObject.clone(preserveId, isDeepClone, preserveReadonlyTimestamps, preserveAutonumber) method, provided that the preserveId parameter wasn’t used or was set to false. The getCloneSourceId() method can only be used within the transaction where the entity is cloned, as clone information doesn’t persist in subsequent transactions.

• getErrors()

  Returns a list of Database.Error objects for an SObject instance. If the SObject has no errors, an empty list is returned.

• getOptions()

  Returns the database.DMLOptions object for the SObject.

• getPopulatedFieldsAsMap()

  Returns a map of populated field names and their corresponding values. The map contains only the fields that have been populated in memory for the SObject instance.

• getSObject(fieldName)

  Returns the value for the specified field. This method is primarily used with dynamic DML to access values for external IDs.

• getSObject(field)

  Returns the value for the field specified by the field token Schema.sObjectField, such as Schema.MyObj.MyExternalId. This method is primarily used with dynamic DML to access values for external IDs.

• getSObjects(fieldName)

  Returns the values for the specified field. This method is primarily used with dynamic DML to access values for associated objects, such as child relationships.

• getSObjects(fieldName)

  Returns the value for the field specified by the field token Schema.fieldName, such as Schema.Account.Contact. This method is primarily used with dynamic DML to access values for associated objects, such as child relationships.

• getSObjectType()

  Returns the token for this SObject. This method is primarily used with describe information.

• getQuickActionName()

  Retrieves the name of a quick action associated with this SObject. Typically used in triggers.

• hasErrors()

  Returns true if an SObject instance has associated errors. The error message can be associated to the SObject instance by using SObject.addError(), validation rules, or by other means.

• isClone()

  Returns true if an entity is cloned from something, even if the entity hasn’t been saved. The method can only be used within the transaction where the entity is cloned, as clone information doesn’t persist in subsequent transactions.

• isSet(fieldName)

  Returns information about the queried sObject field. Returns true if the sObject field is populated, either by direct assignment or by inclusion in a SOQL query. Returns false if the sObject field isn’t set. If an invalid field is specified, an SObjectException is thrown.

• isSet(field)

  Returns information about the queried sObject field. Returns true if the sObject field is populated, either by direct assignment or by inclusion in a SOQL query. Returns false if the sObject field isn’t set. If an invalid field is specified, an SObjectException is thrown.

• put(fieldName, value)

  Sets the value for the specified field and returns the previous value for the field.

• put(field, value)

  Sets the value for the field specified by the field token Schema.sObjectField, such as Schema.Account.AccountNumber and returns the previous value for the field.

• putSObject(fieldName, value)

  Sets the value for the specified field. This method is primarily used with dynamic DML for setting external IDs. The method returns the previous value of the field.

• putSObject(fieldName, value)

  Sets the value for the field specified by the token Schema.SObjectType. This method is primarily used with dynamic DML for setting external IDs. The method returns the previous value of the field.

• recalculateFormulas()

  Deprecated as of API version 57.0. Use the recalculateFormulas() method in the System.Formula class instead.

• setOptions(DMLOptions)

  Sets the DMLOptions object for the SObject.

Marks a trigger record with a custom error message and prevents any DML operation from occurring.

public Void addError(String errorMsg)

• errorMsg:

  Type: String

  The error message to mark the record with.

Type: Void

When used on Trigger.new in insert and update triggers, and on Trigger.old in delete triggers, the error message is displayed in the application interface.

See Triggers and Trigger Exceptions.

This method escapes any HTML markup in the specified error message. The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. As a result, HTML markup is not rendered; instead, it is displayed as text in the Salesforce user interface.

When used in Visualforce controllers, the generated message is added to the collection of errors for the page. For more information, see Validation Rules and Standard Controllers in the Visualforce Developer’s Guide.

Marks a trigger record with a custom error message, specifies if the error message should be escaped, and prevents any DML operation from occurring.

public Void addError(String errorMsg, Boolean escape)

• errorMsg:

  Type: String

  The error message to mark the record with.

• escape:

  Type: Boolean

  Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false). This parameter is ignored in both Lightning Experience and the Salesforce mobile app, and the HTML is always escaped. The escape parameter only applies in Salesforce Classic.

Type: Void

The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. As a result, HTML markup is not rendered; instead, it is displayed as text in the Salesforce user interface.

Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include HTML markup in the error message, call this method with a false escape argument. Make sure that you escape any dynamic content, such as input field values. Otherwise, specify true for the escape argument or call addError(String errorMsg) instead.

Marks a trigger record with a custom error message and prevents any DML operation from occurring.

public Void addError(Exception exceptionError)

• exceptionError:

  Type: System.Exception

  An Exception object or a custom exception object that contains the error message to mark the record with.

Type: Void

When used on Trigger.new in insert and update triggers, and on Trigger.old in delete triggers, the error message is displayed in the application interface.

See Triggers and Trigger Exceptions.

This method escapes any HTML markup in the specified error message. The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. As a result, HTML markup is not rendered; instead, it is displayed as text in the Salesforce user interface.

When used in Visualforce controllers, the generated message is added to the collection of errors for the page. For more information, see Validation Rules and Standard Controllers in the Visualforce Developer’s Guide.

This trigger marks the first record in Trigger.new with the exception.

Marks a trigger record with a custom exception error message, specifies whether or not the exception error message should be escaped, and prevents any DML operation from occurring.

public Void addError(Exception exceptionError, Boolean escape)

• exceptionError:

  Type: System.Exception

  An Exception object or a custom exception object that contains the error message to mark the record with.

• escape:

  Type: Boolean

  Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false). This parameter is ignored in both Lightning Experience and the Salesforce mobile app, and the HTML is always escaped. The escape parameter only applies in Salesforce Classic.

Type: Void

The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. As a result, HTML markup is not rendered; instead, it is displayed as text in the Salesforce user interface.

Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include HTML markup in the error message, call this method with a false escape argument. Make sure that you escape any dynamic content, such as input field values. Otherwise, specify true for the escape argument or call addError(Exception e) instead.

This trigger marks the first record in Trigger.new with an unescaped exception message.

Dynamically add errors to fields of an SObject associated with the specified field name.

public void addError(String fieldName, String errorMsg)

• fieldName:

  Type: String

  The field name of the SObject .

• errorMsg:

  Type: String

  The error message to be added. HTML special characters in the error message string are always escaped.

Type: void

If the field name is an empty string or null, the error is associated with the SObject and not with a specific field.

Dynamically add errors to an SObject instance associated with the specified field.

public void addError(Schema.SObjectField fieldToken, String errorMsg

• fieldToken:

  Type: Schema.SObjectField

  The field of the SObject instance.

• errorMsg:

  Type: String

  The error message to be added. HTML special characters in the error message string are always escaped.

Type: void

Use this method to add errors to the specified field token of a standard or custom object. If fieldTokenis null, the error is associated with the SObject and not with a specific field.

Dynamically add errors to fields of an SObject associated with the specified field name.

public void addError(String fieldName, String errorMsg, Boolean escape)

• fieldName:

  Type: String

  The field name of the SObject .

• errorMsg:

  Type: String

  The error message to be added.

• escape:

  Type: Boolean

  Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false). This parameter is ignored in both Lightning Experience and the Salesforce mobile app, and the HTML is always escaped. The escape parameter only applies in Salesforce Classic.

Type: void

If the field name is an empty string or null, the error is associated with the SObject and not with a specific field.

The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. As a result, HTML markup is not rendered; instead, it is displayed as text in the Salesforce user interface.

• The escape parameter cannot be disabled in Lightning Experience and in the Salesforce mobile app, and will be ignored.
• Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include HTML markup in the error message, call this method with a false escape argument. Make sure that you escape any dynamic content, such as input field values. Otherwise, specify true for the escape argument or call addError(String fieldName, String errorMsg) instead.

Dynamically add errors to an SObject instance associated with the specified field.

public void addError(Schema.SObjectField fieldToken, String errorMsg, Boolean escape)

• fieldToken:

  Type: Schema.SObjectField

  The field of the SObject instance.

• errorMsg:

  Type: String

  The error message to be added.

• escape:

  Type: Boolean

  Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false). This parameter is ignored in both Lightning Experience and the Salesforce mobile app, and the HTML is always escaped. The escape parameter only applies in Salesforce Classic.

Type: void

Use this method to add errors to the specified field token of a standard or custom object. If fieldTokenis null, the error is associated with the SObject and not with a specific field.

The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. As a result, HTML markup is not rendered; instead, it is displayed as text in the Salesforce user interface.

• The escape parameter cannot be disabled in Lightning Experience and in the Salesforce mobile app, and will be ignored.
• Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include HTML markup in the error message, call this method with a false escape argument. Make sure that you escape any dynamic content, such as input field values. Otherwise, specify true for the escape argument or call addError(Schema.SObjectField fieldToken, String errorMsg) instead.

Clears all field values

public Void clear()

Type: Void

Creates a copy of the SObject record.

public SObject clone(Boolean preserveId)

• preserveId: Type: Boolean Determines whether the ID of the original object is preserved or cleared in the duplicate. If set to true, the ID is copied to the duplicate. The default is false, that is, the ID is cleared.

Type: SObject (of the same type)

For Apex saved using Salesforce API version 22.0 or earlier, the default value for the preserveId argument is true, that is, the ID is preserved.

Creates a copy of the SObject record.

public SObject clone(Boolean preserveId, Boolean isDeepClone)

• preserveId:

  Type: Boolean

  Determines whether the ID of the original object is preserved or cleared in the duplicate. If set to true, the ID is copied to the duplicate. The default is false, that is, the ID is cleared.

• isDeepClone:

  Type: Boolean

  Determines whether the method creates a full copy of the SObject field or just a reference:

  • If set to true, the method creates a full copy of the SObject. All fields on the SObject are duplicated in memory, including relationship fields. Consequently, if you change a field on the cloned SObject, the original SObject isn’t affected.
  • If set to false, the method performs a shallow copy of the SObject fields. All copied relationship fields reference the original SObjects. Consequently, if you change a relationship field on the cloned SObject, the corresponding field on the original SObject is also affected, and vice versa. The default is false.

Type: SObject (of the same type)

For Apex saved using Salesforce API version 22.0 or earlier, the default value for the preserveId argument is true, that is, the ID is preserved.

Creates a copy of the SObject record.

public SObject clone(Boolean preserveId, Boolean isDeepClone, Boolean preserveReadonlyTimestamps)

• preserveId:

  Type: Boolean

  Determines whether the ID of the original object is preserved or cleared in the duplicate. If set to true, the ID is copied to the duplicate. The default is false, that is, the ID is cleared.

• isDeepClone:

  Type: Boolean

  Determines whether the method creates a full copy of the SObject field or just a reference:

  • If set to true, the method creates a full copy of the SObject. All fields on the SObject are duplicated in memory, including relationship fields. Consequently, if you change a field on the cloned SObject, the original SObject isn’t affected.
  • If set to false, the method performs a shallow copy of the SObject fields. All copied relationship fields reference the original SObjects. Consequently, if you change a relationship field on the cloned SObject, the corresponding field on the original SObject is also affected, and vice versa. The default is false.

• preserveReadonlyTimestamps:

  Type: Boolean

  Determines whether the read-only timestamp fields are preserved or cleared in the duplicate. If set to true, the read-only fields CreatedById, CreatedDate, LastModifiedById, and LastModifiedDate are copied to the duplicate. The default is false, that is, the values are cleared.

  Audit field values won’t be persisted to the database via DML on the cloned SObject instance.

Type: SObject (of the same type)

For Apex saved using Salesforce API version 22.0 or earlier, the default value for the preserveId argument is true, that is, the ID is preserved.

Creates a copy of the SObject record.

public SObject clone(Boolean preserveId, Boolean isDeepClone, Boolean preserveReadonlyTimestamps, Boolean preserveAutonumber)

• preserveId:

  Type: Boolean

  Determines whether the ID of the original object is preserved or cleared in the duplicate.

  If set to true, the ID is copied to the duplicate. The default is false, that is, the ID is cleared.

• isDeepClone:

  Type: Boolean

  Determines whether the method creates a full copy of the SObject field or just a reference:

  • If set to true, the method creates a full copy of the SObject. All fields on the SObject are duplicated in memory, including relationship fields. Consequently, if you change a field on the cloned SObject, the original SObject isn’t affected.
  • If set to false, the method performs a shallow copy of the SObject fields. All copied relationship fields reference the original SObjects. Consequently, if you change a relationship field on the cloned SObject, the corresponding field on the original SObject is also affected, and vice versa. The default is false.

• preserveReadonlyTimestamps:

  Type: Boolean

  Determines whether the read-only timestamp fields are preserved or cleared in the duplicate. If set to true, the read-only fields CreatedById, CreatedDate, LastModifiedById, and LastModifiedDate are copied to the duplicate. The default is false, that is, the values are cleared.

  Audit field values won’t be persisted to the database via DML on the cloned SObject instance.

• preserveAutonumber: Type: Boolean

  Determines whether auto number fields of the original object are preserved or cleared in the duplicate. If set to true, auto number fields are copied to the cloned object. The default is false, that is, auto number fields are cleared.

Type: SObject (of the same type)

For Apex saved using Salesforce API version 22.0 or earlier, the default value for the preserveId argument is true, that is, the ID is preserved.

Returns the value for the field specified by fieldName, such as AccountNumber.

public Object get(String fieldName)

• fieldName:

  Type: String

Type: Object

For more information, see Dynamic SOQL.

In API version 34.0 and later, you must include the namespace name to retrieve a field from a field Map using this method. For example, to get the account__c field in the MyNamespace namespace from a fields field Map, use: fields.get(‘MyNamespace__account__c’).

Returns the value for the field specified by the field token Schema.sObjectField, such as Schema.Account.AccountNumber.

public Object get(Schema.sObjectField field)

• field:

  Type: Schema.SObjectField

Type: Object

For more information, see Dynamic SOQL.

Field tokens aren’t available for person accounts. If you access Schema.Account.fieldname, where fieldname is a placeholder value, you get an exception error. Instead, specify the field name as a string.

Returns the ID of the entity from which an object was cloned. You can use it for objects cloned through the Salesforce user interface. You can also use it for objects created using the System.SObject.clone(preserveId, isDeepClone, preserveReadonlyTimestamps, preserveAutonumber) method, provided that the preserveId parameter wasn’t used or was set to false. The getCloneSourceId() method can only be used within the transaction where the entity is cloned, as clone information doesn’t persist in subsequent transactions.

public Id getCloneSourceId()

Type: Id

If A is cloned to B, B is cloned to C, and C is cloned to D, then B, C, and D all point back to A as their clone source.

Returns a list of Database.Error objects for an SObject instance. If the SObject has no errors, an empty list is returned.

public List<Database.Error> getErrors()

Type: List<Database.Error>

Returns the database.DMLOptions object for the SObject.

public Database.DMLOptions getOptions()

Type: Database.DMLOptions

Returns a map of populated field names and their corresponding values. The map contains only the fields that have been populated in memory for the SObject instance.

public Map<String,Object> getPopulatedFieldsAsMap()

Type: Map<String,Object>

A map of field names and their corresponding values.

The returned map contains only the fields that have been populated in memory for the SObject instance, which makes it easy to iterate over those fields. A field is populated in memory in these cases.

• The field has been queried by a SOQL statement, and the field is not null.
• The field has been explicitly set before the call to the getPopulatedFieldsAsMap() method.

Fields on related objects that are queried or set are also returned in the map.

The following example iterates over the map returned by the getPopulatedFieldsAsMap() method after a SOQL query.

This example iterates over the map returned by the getPopulatedFieldsAsMap() method after fields on the SObject are explicitly set.

The following example shows how to use the getPopulatedFieldsAsMap() method with related objects.

In API version 39.0 and later, getPopulatedFieldsAsMap returns all values set on the SObject, even if values were set after the record was queried. This behavior is dependent on the version of the apex class calling this method and not on the version of the class that generated the SObject. If you query an SObject at API version 20.0, and then call this method in a class with API version 40.0, you will get the full set of fields.

Returns the value for the specified field. This method is primarily used with dynamic DML to access values for external IDs.

public SObject getSObject(String fieldName)

• fieldName:

  Type: String

Type: SObject

Returns the value for the field specified by the field token Schema.sObjectField, such as Schema.MyObj.MyExternalId. This method is primarily used with dynamic DML to access values for external IDs.

public SObject getSObject(Schema.SObjectField field)

• field:

  Type: Schema.SObjectField

Type: SObject

If the method references polymorphic fields, a Name object is returned. Use the TYPEOF clause in the SOQL SELECT statement to directly get results that depend on the runtime object type referenced by the polymorphic field. See Working with Polymorphic Relationships in SOQL Queries.

Returns the values for the specified field. This method is primarily used with dynamic DML to access values for associated objects, such as child relationships.

public SObject[] getSObjects(String fieldName)

• fieldName:

  Type: String

Type: SObject[]

For more information, see Dynamic DML.

Returns the value for the field specified by the field token Schema.fieldName, such as Schema.Account.Contact. This method is primarily used with dynamic DML to access values for associated objects, such as child relationships.

public SObject[] getSObjects(Schema.SObjectType fieldName)

• fieldName:

  Type: Schema.SObjectType

Type: SObject[]

Returns the token for this SObject. This method is primarily used with describe information.

public Schema.SObjectType getSObjectType()

Type: Schema.SObjectType

For more information, see apex_dynamic_describe_objects_understanding.

Retrieves the name of a quick action associated with this SObject. Typically used in triggers.

public String getQuickActionName()

Type: String

Returns true if an SObject instance has associated errors. The error message can be associated to the SObject instance by using SObject.addError(), validation rules, or by other means.

public Boolean hasErrors()

Type: Boolean

Returns true if an entity is cloned from something, even if the entity hasn’t been saved. The method can only be used within the transaction where the entity is cloned, as clone information doesn’t persist in subsequent transactions.

public Boolean isClone()

Type: Boolean

Returns information about the queried sObject field. Returns true if the sObject field is populated, either by direct assignment or by inclusion in a SOQL query. Returns false if the sObject field isn’t set. If an invalid field is specified, an SObjectException is thrown.

public Boolean isSet(String fieldName)

• fieldName:

  Type: String

Type: Boolean

The isSet method doesn’t check if a field is accessible to a specific user via org permissions or other specialized access permissions.

Returns information about the queried sObject field. Returns true if the sObject field is populated, either by direct assignment or by inclusion in a SOQL query. Returns false if the sObject field isn’t set. If an invalid field is specified, an SObjectException is thrown.

public Boolean isSet(Schema.SObjectField field)

• field:

  Type:SObjectField Class

Type: Boolean

The isSet method doesn’t check if a field is accessible to a specific user via org permissions or other specialized access permissions.

Sets the value for the specified field and returns the previous value for the field.

public Object put(String fieldName, Object value)

• fieldName:

  Type: String

• value:

  Type: Object

Type: Object

Sets the value for the field specified by the field token Schema.sObjectField, such as Schema.Account.AccountNumber and returns the previous value for the field.

public Object put(Schema.SObjectField field, Object value)

• field:

  Type: Schema.SObjectField

• value:

  Type: Object

Type: Object

Field tokens aren’t available for person accounts. If you access Schema.Account.fieldname, where fieldname is a placeholder value, you get an exception error. Instead, specify the field name as a string.

Sets the value for the specified field. This method is primarily used with dynamic DML for setting external IDs. The method returns the previous value of the field.

public SObject putSObject(String fieldName, SObject value)

• fieldName:

  Type: String

• value:

  Type: SObject

Type: SObject

Sets the value for the field specified by the token Schema.SObjectType. This method is primarily used with dynamic DML for setting external IDs. The method returns the previous value of the field.

public SObject putSObject(Schema.SObjectType fieldName, SObject value)

• fieldName:

  Type: Schema.SObjectType

• value:

  Type: SObject

Type: SObject

Deprecated as of API version 57.0. Use the recalculateFormulas() method in the System.Formula class instead.

public Void recalculateFormulas()

Type: Void

This method doesn’t recalculate cross-object formulas. If you call this method on objects that have both cross-object and non-cross-object formula fields, only the non-cross-object formula fields are recalculated.

Each recalculateFormulas call counts against the SOQL query limits. See Execution Governors and Limits.

See Also

• recalculateFormulas(sobjects)
• What Is a Cross-Object Formula?

Sets the DMLOptions object for the SObject.

public Void setOptions(database.DMLOptions DMLOptions)

• DMLOptions:

  Type: Database.DMLOptions

Type: Void