ssjs.guide SFMC
⌘K

DataExtension

Initialize a Data Extension object for row-level CRUD operations. The starting point for all Core library DE operations.

DataExtension is a Core library object that provides object-oriented access to Data Extensions. Initialize it with DataExtension.Init(), then use the .Rows and .Fields properties.

Methods

Method Returns Description
DataExtension.Init(key) DataExtensionInstance Initialize a DataExtension object by external key
DataExtension.Add(properties) DataExtensionInstance Create a new data extension
DataExtension.Retrieve(filter, [queryAllAccounts]) object[] Retrieve data extensions matching a filter

DataExtension.Init

Initializes a DataExtension instance bound to the specified external key. Required before invoking any Fields or Rows sub-namespace method on the returned instance.

Syntax

DataExtension.Init(key)

Parameters

Name Type Required Description
key string Yes The External Key of the Data Extension

Return value

DataExtensionInstance — access rows via .Rows, fields via .Fields.

Examples

Initialize and retrieve all rows

Platform.Load("core", "1.1.5");
var de = DataExtension.Init("MyDE_ExternalKey");
var rows = de.Rows.Retrieve();
// rows is an array of objects
for (var i = 0; i < rows.length; i++) {
    Write(rows[i].Email + "<br>");
}

Initialize and retrieve with filter

Platform.Load("core", "1.1.5");
var de = DataExtension.Init("Orders");
var filter = {
    Property: "Status",
    SimpleOperator: "equals",
    Value: "pending"
};
var pendingOrders = de.Rows.Retrieve(filter);

Insert a row

Platform.Load("core", "1.1.5");
var de = DataExtension.Init("EventLog");
de.Rows.Add([{
    EventType: "pageview",
    Page: "/home",
    Timestamp: Platform.Function.Now(),
    SubscriberKey: subscriberKey
}]);

Update a row

Platform.Load("core", "1.1.5");
var de = DataExtension.Init("Contacts");
de.Rows.Update(
    { Status: "active", LastSeen: Platform.Function.Now() }, // columns to set
    ["SubscriberKey"],                                       // key columns
    [subscriberKey]                                          // key values
);

Remove rows

Platform.Load("core", "1.1.5");
var de = DataExtension.Init("TempData");
de.Rows.Remove(["SubscriberKey"], [subscriberKey]);

DataExtension.Add

Creates a new data extension from the supplied properties and returns an initialized DataExtension instance. Unlike most static Add methods, this returns a DataExtensionInstance, not "OK".

Syntax

DataExtension.Add(properties)

Parameters

Name Type Required Description
properties object Yes CustomerKey, Name, Fields[], optional SendableInfo

Return value

DataExtensionInstance

Examples

Platform.Load("core", "1.1.5");
var deObj = {
    CustomerKey: "SendableDE",
    Name: "Sendable Data Extension",
    Fields: [
        { Name: "SubKey", FieldType: "Text", IsPrimaryKey: true, MaxLength: 50, IsRequired: true },
        { Name: "SecondField", FieldType: "Text", MaxLength: 50 }
    ],
    SendableInfo: {
        Field: { Name: "SubKey", FieldType: "Text" },
        RelatesOn: "Subscriber Key"
    }
};
var de = DataExtension.Add(deObj);

DataExtension.Retrieve

Returns an array of data extensions matching the specified filter. Pass queryAllAccounts: true to search all accounts accessible to the authenticated user.

Syntax

DataExtension.Retrieve(filter, [queryAllAccounts])

Parameters

Name Type Required Description
filter object Yes PascalCase WSProxy-style filter object: {Property, SimpleOperator, Value}
queryAllAccounts boolean No When true, search across all accessible accounts. Defaults to false.

Return value

object[]

Examples

Platform.Load("core", "1.1.5");
var results = DataExtension.Retrieve({ Property: "CustomerKey", SimpleOperator: "equals", Value: "myDEKey" });

Notes

External Key vs Name

DataExtension.Init() requires the External Key, not the display name. Find it in:

  • Email Studio → Data Extensions → Edit → External Key
  • Contact Builder → Data Extensions → (click DE name) → Properties

CloudPage Retrieve Bug

de.Rows.Retrieve() does not work reliably on CloudPages without a filter argument. Always pass a filter, or use Platform.Function.LookupRows() as a workaround. See Known Bugs for details.

// On CloudPages, this may return empty results:
var rows = de.Rows.Retrieve();

// Use a filter instead:
var rows = de.Rows.Retrieve({ Property: "Active", SimpleOperator: "equals", Value: "1" });

// Or use Platform.Function:
var rows = Platform.Function.LookupRows("MyDE", ["Active"], ["1"]);

See Also

See Also