ssjs.guide SFMC

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 property to retrieve, insert, update, or remove rows.

Syntax

Platform.Load("core", "1.1.5");
var de = DataExtension.Init(externalKey);

Parameters

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

Return Value

Returns a DataExtension object. Access rows via de.Rows.

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);

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