ampscript-data 3.7.0 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1118 @@
1
+ // AUTO-SPLIT from the original single-file src/index.js. Data moved verbatim.
2
+ // AMPscript FUNCTIONS — category: Data Extension (21 entries).
3
+
4
+ import { BOOLEAN_LIKE_LITERAL_VALUES, INF } from '../constants.js';
5
+
6
+ export const DATA_EXTENSION_FUNCTIONS = [
7
+ {
8
+ name: 'ClaimRow',
9
+ supportedInCloudPage: true,
10
+ supportedInEmail: true,
11
+ mcnSince: null,
12
+ handlebarsEquivalent: null,
13
+ mcnNotes: null,
14
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-claim-row.html',
15
+ guideUrl: 'https://ampscript.guide/claimrow/',
16
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/claimrow/',
17
+ minArgs: 4,
18
+ maxArgs: INF,
19
+ category: 'Data Extension',
20
+ description:
21
+ 'Atomically claims an unclaimed row in a data extension by setting a key column value.',
22
+ params: [
23
+ {
24
+ name: 'dataExt',
25
+ mcnSince: null,
26
+ mcnNotes: null,
27
+ description: 'The data extension that contains the value to return (hard-coded)',
28
+ type: 'string',
29
+ },
30
+ {
31
+ name: 'claimColumn',
32
+ mcnSince: null,
33
+ mcnNotes: null,
34
+ description: 'The column the function uses to track whether a row is claimed',
35
+ type: 'string',
36
+ },
37
+ {
38
+ name: 'claimantColumn',
39
+ mcnSince: null,
40
+ mcnNotes: null,
41
+ description:
42
+ 'The column the function uses to track the subscriber who claimed the row',
43
+ type: 'string',
44
+ },
45
+ {
46
+ name: 'claimantValue',
47
+ mcnSince: null,
48
+ mcnNotes: null,
49
+ description:
50
+ 'The value to enter in the claimantColumn when the function claims a row',
51
+ },
52
+ {
53
+ name: 'additionalColumnNameN',
54
+ mcnSince: null,
55
+ mcnNotes: null,
56
+ description: 'Additional column name to populate',
57
+ type: 'string',
58
+ optional: true,
59
+ },
60
+ {
61
+ name: 'additionalColumnValueN',
62
+ mcnSince: null,
63
+ mcnNotes: null,
64
+ description: 'Additional column value to populate',
65
+ optional: true,
66
+ },
67
+ ],
68
+ returnType: 'row',
69
+ returnDescription: 'The claimed row, or an empty row when none could be claimed.',
70
+ repeat: [{ startIndex: 4, groupSize: 2, minGroups: 0 }],
71
+ syntax: 'ClaimRow(dataExt, claimColumn, claimantColumn, claimantValue[, additionalColumnNameN, additionalColumnValueN, ...])',
72
+ example: "%%[ SET @row = ClaimRow('Coupons', 'Claimed', 'SubKey', _subscriberkey) ]%%",
73
+ isConfirmed: true,
74
+ differsFromOfficialDocs: true,
75
+ officialDocsNote:
76
+ 'In a CloudPage context, against a data extension built to the documented claimable schema (Text primary key, Text claimant column, required non-nullable Boolean claim column defaulting to False, nullable Date column): each call passing a new claimant value claims the next unclaimed row and advances — four distinct claimants receive C1, C2, C3, C4 in order, each row flipping to claimed with its claimant recorded and ClaimedDate auto-populated. Re-calling with a claimant value that already holds a row returns that same row rather than advancing (per-subscriber idempotency). The official reference states that ClaimRow returns an exception when no unclaimed rows remain; at runtime it instead returns an empty row that does not abort the page (Empty() on it is true), so a caller must guard with Empty() rather than expecting a raised error. Reusing one claimant value never advances, because of the idempotency rule rather than a provisioning gap.',
77
+ },
78
+ {
79
+ name: 'ClaimRowValue',
80
+ supportedInCloudPage: true,
81
+ supportedInEmail: true,
82
+ mcnSince: null,
83
+ handlebarsEquivalent: null,
84
+ mcnNotes: null,
85
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-claim-row-value.html',
86
+ guideUrl: 'https://ampscript.guide/claimrowvalue/',
87
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/claimrowvalue/',
88
+ minArgs: 6,
89
+ maxArgs: INF,
90
+ category: 'Data Extension',
91
+ description:
92
+ 'Atomically claims a row and returns a specific column value from it, or a caller-supplied fallback when no unclaimed rows remain.',
93
+ params: [
94
+ {
95
+ name: 'dataExt',
96
+ mcnSince: null,
97
+ mcnNotes: null,
98
+ description: 'The data extension that contains the value to return (hard-coded)',
99
+ type: 'string',
100
+ },
101
+ {
102
+ name: 'returnValueColumn',
103
+ description: 'The name of the column that contains the data to return',
104
+ type: 'string',
105
+ },
106
+ {
107
+ name: 'claimColumn',
108
+ mcnSince: null,
109
+ mcnNotes: null,
110
+ description: 'The column the function uses to track whether a row is claimed',
111
+ type: 'string',
112
+ },
113
+ {
114
+ name: 'fallbackValue',
115
+ mcnSince: null,
116
+ mcnNotes: null,
117
+ description:
118
+ 'Value returned when no unclaimed rows remain (required at runtime, despite ampscript.guide marking it optional)',
119
+ },
120
+ {
121
+ name: 'claimantColumn',
122
+ mcnSince: null,
123
+ mcnNotes: null,
124
+ description:
125
+ 'The column the function uses to track the subscriber who claimed the row (required at runtime)',
126
+ type: 'string',
127
+ },
128
+ {
129
+ name: 'claimantValue',
130
+ mcnSince: null,
131
+ mcnNotes: null,
132
+ description:
133
+ 'The value to enter in the claimant column when the function claims a row (required at runtime)',
134
+ },
135
+ {
136
+ name: 'additionalColumnNameN',
137
+ mcnSince: null,
138
+ mcnNotes: null,
139
+ description:
140
+ 'Name of a further column to write on the claimed row (record extra context at claim time). Repeatable as name/value pairs.',
141
+ type: 'string',
142
+ optional: true,
143
+ },
144
+ {
145
+ name: 'additionalColumnValueN',
146
+ mcnSince: null,
147
+ mcnNotes: null,
148
+ description:
149
+ 'Value written to the paired additionalColumnNameN column on the claimed row',
150
+ optional: true,
151
+ },
152
+ ],
153
+ returnType: 'string',
154
+ returnDescription:
155
+ 'The value from the requested column of the claimed row, or the fallbackValue when no unclaimed rows remain.',
156
+ repeat: [{ startIndex: 6, groupSize: 2, minGroups: 0 }],
157
+ syntax: 'ClaimRowValue(dataExt, returnValueColumn, claimColumn, fallbackValue, claimantColumn, claimantValue[, additionalColumnNameN, additionalColumnValueN, ...])',
158
+ example:
159
+ "%%=ClaimRowValue('Coupons', 'Code', 'Claimed', 'SOLD OUT', 'SubKey', _subscriberkey)=%%",
160
+ isConfirmed: true,
161
+ differsFromOfficialDocs: false,
162
+ },
163
+ {
164
+ name: 'DataExtensionRowCount',
165
+ supportedInCloudPage: true,
166
+ supportedInEmail: true,
167
+ mcnSince: null,
168
+ handlebarsEquivalent: null,
169
+ mcnNotes: null,
170
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-de-row-count.html',
171
+ guideUrl: 'https://ampscript.guide/dataextensionrowcount/',
172
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/dataextensionrowcount/',
173
+ isConfirmed: true,
174
+ differsFromOfficialDocs: false,
175
+ minArgs: 1,
176
+ maxArgs: 1,
177
+ category: 'Data Extension',
178
+ description: 'Returns the total number of rows in a data extension.',
179
+ params: [
180
+ {
181
+ name: 'dataExtensionName',
182
+ mcnSince: null,
183
+ mcnNotes: null,
184
+ description: 'Data extension name or external key',
185
+ type: 'string',
186
+ },
187
+ ],
188
+ returnType: 'number',
189
+ returnDescription: 'The total number of rows in the data extension.',
190
+ syntax: 'DataExtensionRowCount(dataExtensionName)',
191
+ example: "%%=DataExtensionRowCount('MyDE')=%%",
192
+ },
193
+ {
194
+ name: 'DeleteData',
195
+ supportedInCloudPage: true,
196
+ supportedInEmail: false,
197
+ mcnSince: null,
198
+ handlebarsEquivalent: null,
199
+ mcnNotes: null,
200
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-delete-data.html',
201
+ guideUrl: 'https://ampscript.guide/deletedata/',
202
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/deletedata/',
203
+ isConfirmed: true,
204
+ differsFromOfficialDocs: true,
205
+ officialDocsNote:
206
+ 'Email/send-context finding: DeleteData is not valid in sendable email content. An isolated DeleteData(...) is rejected with HTTP 400 errorcode 10005 ("DeleteData Function is not valid in content. This function is only allowed in a non batch context."). A send is a batch operation, so the DeleteData/*Data write family cannot run inside a sendable email; use the DeleteDE variant instead, which the send parser accepts in sendable content. This is a CloudPage / landing-page (non-batch) feature.',
207
+ minArgs: 3,
208
+ maxArgs: INF,
209
+ category: 'Data Extension',
210
+ description:
211
+ 'Deletes rows from a data extension matching the specified key column criteria.',
212
+ params: [
213
+ {
214
+ name: 'dataExt',
215
+ description:
216
+ 'The name of the data extension that contains the data you want to delete',
217
+ type: 'string',
218
+ },
219
+ {
220
+ name: 'columnName1',
221
+ description: 'The name of the column to search for the data you want to delete',
222
+ type: 'string',
223
+ },
224
+ {
225
+ name: 'valueToDelete1',
226
+ description: 'The value that determines which row to delete',
227
+ },
228
+ {
229
+ name: 'columnNameN',
230
+ mcnSince: null,
231
+ mcnNotes: null,
232
+ description: 'Additional filter column name',
233
+ type: 'string',
234
+ optional: true,
235
+ },
236
+ { name: 'valueToDeleteN', description: 'Additional filter value', optional: true },
237
+ ],
238
+ returnType: 'number',
239
+ returnDescription: 'The number of rows deleted.',
240
+ repeat: [{ startIndex: 1, groupSize: 2, minGroups: 1 }],
241
+ syntax: 'DeleteData(dataExt, columnName1, valueToDelete1[, columnNameN, valueToDeleteN, ...])',
242
+ example: "%%=DeleteData('Subscribers', 'SubscriberKey', _subscriberkey)=%%",
243
+ },
244
+ {
245
+ name: 'DeleteDE',
246
+ supportedInCloudPage: true,
247
+ supportedInEmail: true,
248
+ mcnSince: null,
249
+ handlebarsEquivalent: null,
250
+ mcnNotes: null,
251
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-delete-de.html',
252
+ guideUrl: 'https://ampscript.guide/deletede/',
253
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/deletede/',
254
+ isConfirmed: true,
255
+ differsFromOfficialDocs: false,
256
+ minArgs: 3,
257
+ maxArgs: INF,
258
+ category: 'Data Extension',
259
+ description: 'Deletes rows from a data extension. Email-context variant of DeleteData.',
260
+ params: [
261
+ {
262
+ name: 'dataExt',
263
+ description:
264
+ 'The name of the data extension that contains the data you want to delete',
265
+ type: 'string',
266
+ },
267
+ {
268
+ name: 'columnName1',
269
+ description: 'The name of the column to search for the data you want to delete',
270
+ type: 'string',
271
+ },
272
+ {
273
+ name: 'valueToDelete1',
274
+ description: 'The value that determines which row to delete',
275
+ },
276
+ {
277
+ name: 'columnNameN',
278
+ mcnSince: null,
279
+ mcnNotes: null,
280
+ description: 'Additional filter column name',
281
+ type: 'string',
282
+ optional: true,
283
+ },
284
+ { name: 'valueToDeleteN', description: 'Additional filter value', optional: true },
285
+ ],
286
+ returnType: 'number',
287
+ returnDescription: 'The number of rows deleted.',
288
+ repeat: [{ startIndex: 1, groupSize: 2, minGroups: 1 }],
289
+ syntax: 'DeleteDE(dataExt, columnName1, valueToDelete1[, columnNameN, valueToDeleteN, ...])',
290
+ example: "%%=DeleteDE('Subscribers', 'SubscriberKey', _subscriberkey)=%%",
291
+ },
292
+ {
293
+ name: 'ExecuteFilter',
294
+ supportedInCloudPage: true,
295
+ supportedInEmail: false,
296
+ mcnSince: null,
297
+ handlebarsEquivalent: null,
298
+ mcnNotes: null,
299
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-execute-filter.html',
300
+ guideUrl: 'https://ampscript.guide/executefilter/',
301
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/executefilter/',
302
+ isConfirmed: true,
303
+ differsFromOfficialDocs: true,
304
+ officialDocsNote:
305
+ 'Email/send-context finding: ExecuteFilter is not valid in sendable email content. An isolated ExecuteFilter(...) is rejected with HTTP 400 errorcode 10004 ("ExecuteFilter Function is not valid in content. This function is only allowed in non sendable content."). It is a CloudPage / landing-page (non-sendable content) feature.',
306
+ minArgs: 1,
307
+ maxArgs: 1,
308
+ category: 'Data Extension',
309
+ description: 'Executes a predefined data filter and returns the resulting rowset.',
310
+ params: [
311
+ {
312
+ name: 'dataFilterExternalId',
313
+ description:
314
+ 'The external ID of the data filter to execute. This function only works with data filters that are based on data extensions',
315
+ type: 'string',
316
+ },
317
+ ],
318
+ returnType: 'rowset',
319
+ returnDescription: 'A rowset containing the rows that match the data filter.',
320
+ syntax: 'ExecuteFilter(dataFilterExternalId)',
321
+ example: "%%[ SET @rows = ExecuteFilter('FilterExternalKey') ]%%",
322
+ },
323
+ {
324
+ name: 'ExecuteFilterOrderedRows',
325
+ supportedInCloudPage: true,
326
+ supportedInEmail: false,
327
+ mcnSince: null,
328
+ handlebarsEquivalent: null,
329
+ mcnNotes: null,
330
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-execute-filter-ordered-rows.html',
331
+ guideUrl: 'https://ampscript.guide/executefilterorderedrows/',
332
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/executefilterorderedrows/',
333
+ isConfirmed: true,
334
+ differsFromOfficialDocs: true,
335
+ officialDocsNote:
336
+ 'Email/send-context finding: ExecuteFilterOrderedRows is not valid in sendable email content. An isolated ExecuteFilterOrderedRows(...) is rejected with HTTP 400 errorcode 10004 ("ExecuteFilterOrderedRows Function is not valid in content. This function is only allowed in non sendable content."). It is a CloudPage / landing-page (non-sendable content) feature.',
337
+ minArgs: 3,
338
+ maxArgs: 3,
339
+ category: 'Data Extension',
340
+ description: 'Executes a predefined data filter and returns results sorted by a column.',
341
+ params: [
342
+ {
343
+ name: 'dataFilterExternalId',
344
+ description:
345
+ 'The external ID of the data filter to execute. This function only works with data filters that are based on data extensions',
346
+ type: 'string',
347
+ },
348
+ {
349
+ name: 'numRows',
350
+ description:
351
+ 'The number of rows to return in the rowset. A value of 0 returns all results. There is no maximum number of rows that can be returned',
352
+ type: 'number',
353
+ },
354
+ {
355
+ name: 'sortColumn',
356
+ description:
357
+ 'The column to sort data by, followed by a space and either "ASC" (for ascending order) or "DESC" (descending)',
358
+ type: 'string',
359
+ },
360
+ ],
361
+ returnType: 'rowset',
362
+ returnDescription: 'A sorted, row-limited rowset of rows that match the data filter.',
363
+ syntax: 'ExecuteFilterOrderedRows(dataFilterExternalId, numRows, sortColumn)',
364
+ example:
365
+ "%%[ SET @rows = ExecuteFilterOrderedRows('FilterExternalKey', 10, 'LastName ASC') ]%%",
366
+ },
367
+ {
368
+ name: 'Field',
369
+ supportedInCloudPage: true,
370
+ supportedInEmail: true,
371
+ mcnSince: 67,
372
+ handlebarsEquivalent: 'get',
373
+ handlebarsExact: false,
374
+ mcnNotes: null,
375
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-field.html',
376
+ guideUrl: 'https://ampscript.guide/field/',
377
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/field/',
378
+ isConfirmed: true,
379
+ differsFromOfficialDocs: false,
380
+ minArgs: 2,
381
+ maxArgs: 3,
382
+ category: 'Data Extension',
383
+ description:
384
+ 'Retrieves the value of a named field from a rowset row. The two-argument form aborts the page when the column is absent; pass the optional third argument as 0 (or false) to get an empty string for a possibly-missing column instead.',
385
+ params: [
386
+ { name: 'row', description: 'Row object from a rowset', type: 'row' },
387
+ { name: 'fieldName', description: 'Column name to retrieve', type: 'string' },
388
+ {
389
+ name: 'exceptionIfNotFound',
390
+ mcnSince: null,
391
+ mcnNotes: null,
392
+ description:
393
+ "If true, the function returns an exception if the specified field doesn't exist. If false, the function returns an empty string if the field doesn't exist. The default value is true.",
394
+ type: 'string|boolean|number',
395
+ enum: BOOLEAN_LIKE_LITERAL_VALUES,
396
+ optional: true,
397
+ default: true,
398
+ },
399
+ ],
400
+ returnType: 'string',
401
+ returnDescription: 'The value of the named field from the supplied row.',
402
+ syntax: 'Field(row, fieldName[, exceptionIfNotFound])',
403
+ example: "%%=Field(Row(@rows, 1), 'Name')=%%",
404
+ },
405
+ {
406
+ name: 'InsertData',
407
+ supportedInCloudPage: true,
408
+ supportedInEmail: false,
409
+ mcnSince: null,
410
+ handlebarsEquivalent: null,
411
+ mcnNotes: null,
412
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-insert-data.html',
413
+ guideUrl: 'https://ampscript.guide/insertdata/',
414
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/insertdata/',
415
+ isConfirmed: true,
416
+ differsFromOfficialDocs: true,
417
+ officialDocsNote:
418
+ 'Email/send-context finding: InsertData is not valid in sendable email content. An isolated InsertData(...) is rejected with HTTP 400 errorcode 10005 ("InsertData Function is not valid in content. This function is only allowed in a non batch context."). A send is a batch operation, so the InsertData/*Data write family cannot run inside a sendable email; use the InsertDE variant instead, which the send parser accepts in sendable content. This is a CloudPage / landing-page (non-batch) feature.',
419
+ minArgs: 3,
420
+ maxArgs: INF,
421
+ category: 'Data Extension',
422
+ description: 'Inserts a new row into a data extension.',
423
+ params: [
424
+ {
425
+ name: 'dataExt',
426
+ description: 'The name of the data extension to insert data into',
427
+ type: 'string',
428
+ },
429
+ {
430
+ name: 'columnName1',
431
+ description: 'The name of the column to insert into the data extension',
432
+ type: 'string',
433
+ },
434
+ {
435
+ name: 'valueToInsert1',
436
+ description: 'The value to insert into the specified column',
437
+ },
438
+ {
439
+ name: 'columnNameN',
440
+ mcnSince: null,
441
+ mcnNotes: null,
442
+ description: 'Additional column name',
443
+ type: 'string',
444
+ optional: true,
445
+ },
446
+ { name: 'valueToInsertN', description: 'Additional column value', optional: true },
447
+ ],
448
+ returnType: 'number',
449
+ returnDescription: 'The number of rows inserted.',
450
+ repeat: [{ startIndex: 1, groupSize: 2, minGroups: 1 }],
451
+ syntax: 'InsertData(dataExt, columnName1, valueToInsert1[, columnNameN, valueToInsertN, ...])',
452
+ example: "%%=InsertData('Log', 'SubscriberKey', _subscriberkey, 'Status', 'Sent')=%%",
453
+ },
454
+ {
455
+ name: 'InsertDE',
456
+ supportedInCloudPage: true,
457
+ supportedInEmail: true,
458
+ mcnSince: null,
459
+ handlebarsEquivalent: null,
460
+ mcnNotes: null,
461
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-insert-de.html',
462
+ guideUrl: 'https://ampscript.guide/insertde/',
463
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/insertde/',
464
+ isConfirmed: true,
465
+ differsFromOfficialDocs: false,
466
+ minArgs: 3,
467
+ maxArgs: INF,
468
+ category: 'Data Extension',
469
+ description:
470
+ 'Inserts a new row into a data extension. Email-context variant of InsertData.',
471
+ params: [
472
+ {
473
+ name: 'dataExt',
474
+ description: 'The name of the data extension to insert data into',
475
+ type: 'string',
476
+ },
477
+ {
478
+ name: 'columnName1',
479
+ description: 'The name of the column to insert into the data extension',
480
+ type: 'string',
481
+ },
482
+ {
483
+ name: 'valueToInsert1',
484
+ description: 'The value to insert into the specified column',
485
+ },
486
+ {
487
+ name: 'columnNameN',
488
+ mcnSince: null,
489
+ mcnNotes: null,
490
+ description: 'Additional column name',
491
+ type: 'string',
492
+ optional: true,
493
+ },
494
+ { name: 'valueToInsertN', description: 'Additional column value', optional: true },
495
+ ],
496
+ returnType: 'number',
497
+ returnDescription: 'The number of rows inserted.',
498
+ repeat: [{ startIndex: 1, groupSize: 2, minGroups: 1 }],
499
+ syntax: 'InsertDE(dataExt, columnName1, valueToInsert1[, columnNameN, valueToInsertN, ...])',
500
+ example: "%%=InsertDE('Log', 'SubscriberKey', _subscriberkey, 'Status', 'Sent')=%%",
501
+ },
502
+ {
503
+ name: 'Lookup',
504
+ supportedInCloudPage: true,
505
+ supportedInEmail: true,
506
+ mcnSince: 67,
507
+ handlebarsEquivalent: 'queryFirst',
508
+ handlebarsExact: false,
509
+ mcnNotes:
510
+ 'In MCN, search arguments must be provided in column/value pairs - an odd count causes an error. All filter keys must fully specify the composite primary key.',
511
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-lookup.html',
512
+ guideUrl: 'https://ampscript.guide/lookup/',
513
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/lookup/',
514
+ isConfirmed: true,
515
+ differsFromOfficialDocs: false,
516
+ minArgs: 4,
517
+ maxArgs: INF,
518
+ category: 'Data Extension',
519
+ description:
520
+ 'Returns a single field value from the first matching row in a data extension. A no-match returns an empty string.',
521
+ params: [
522
+ {
523
+ name: 'dataObject',
524
+ description:
525
+ 'The data object (data extension or marketing object) that contains the data to look up',
526
+ type: 'string',
527
+ },
528
+ {
529
+ name: 'returnColumn',
530
+ description: 'The name of the column to return data from',
531
+ type: 'string',
532
+ },
533
+ {
534
+ name: 'searchColumn1',
535
+ description: 'The name of the column to search',
536
+ type: 'string',
537
+ },
538
+ { name: 'searchValue1', description: 'The value that identifies the rows to retrieve' },
539
+ {
540
+ name: 'searchColumnN',
541
+ mcnSince: null,
542
+ mcnNotes: null,
543
+ description: 'Additional filter column',
544
+ type: 'string',
545
+ optional: true,
546
+ },
547
+ { name: 'searchValueN', description: 'Additional filter value', optional: true },
548
+ ],
549
+ returnType: 'string',
550
+ returnDescription: 'The value from the requested column of the first matching row.',
551
+ repeat: [{ startIndex: 2, groupSize: 2, minGroups: 1 }],
552
+ syntax: 'Lookup(dataObject, returnColumn, searchColumn1, searchValue1[, searchColumnN, searchValueN, ...])',
553
+ example: "%%=Lookup('MyDE', 'Email', 'ID', '123')=%%",
554
+ },
555
+ {
556
+ name: 'LookupOrderedRows',
557
+ supportedInCloudPage: true,
558
+ supportedInEmail: true,
559
+ mcnSince: null,
560
+ handlebarsEquivalent: 'query',
561
+ handlebarsExact: false,
562
+ mcnNotes: null,
563
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-lookup-ordered-rows.html',
564
+ guideUrl: 'https://ampscript.guide/lookuporderedrows/',
565
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/lookuporderedrows/',
566
+ isConfirmed: true,
567
+ differsFromOfficialDocs: false,
568
+ minArgs: 5,
569
+ maxArgs: INF,
570
+ category: 'Data Extension',
571
+ description: 'Returns a sorted rowset of matching rows from a data extension.',
572
+ params: [
573
+ {
574
+ name: 'dataExt',
575
+ description: 'The name of the data extension that contains the data to retrieve',
576
+ type: 'string',
577
+ },
578
+ {
579
+ name: 'numRows',
580
+ description:
581
+ 'The number of rows to return. A value less than 1 returns all rows (max 2,000)',
582
+ type: 'number',
583
+ },
584
+ {
585
+ name: 'sortColumn',
586
+ mcnSince: null,
587
+ mcnNotes: null,
588
+ description:
589
+ 'The column to sort data by, followed by ASC or DESC (case-insensitive)',
590
+ type: 'string',
591
+ },
592
+ {
593
+ name: 'searchColumn1',
594
+ description: 'The name of the column to search',
595
+ type: 'string',
596
+ },
597
+ { name: 'searchValue1', description: 'The value that identifies the rows to retrieve' },
598
+ {
599
+ name: 'searchColumnN',
600
+ mcnSince: null,
601
+ mcnNotes: null,
602
+ description: 'Additional filter column',
603
+ type: 'string',
604
+ optional: true,
605
+ },
606
+ { name: 'searchValueN', description: 'Additional filter value', optional: true },
607
+ ],
608
+ returnType: 'rowset',
609
+ returnDescription: 'A sorted, row-limited rowset of matching rows.',
610
+ repeat: [{ startIndex: 3, groupSize: 2, minGroups: 1 }],
611
+ syntax: 'LookupOrderedRows(dataExt, numRows, sortColumn, searchColumn1, searchValue1[, searchColumnN, searchValueN, ...])',
612
+ example:
613
+ "%%[ SET @rows = LookupOrderedRows('Orders', 5, 'OrderDate DESC', 'SubKey', _subscriberkey) ]%%",
614
+ },
615
+ {
616
+ name: 'LookupOrderedRowsCS',
617
+ supportedInCloudPage: true,
618
+ supportedInEmail: true,
619
+ mcnSince: null,
620
+ handlebarsEquivalent: 'query',
621
+ handlebarsExact: false,
622
+ mcnNotes: null,
623
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-lookup-ordered-rows-cs.html',
624
+ guideUrl: 'https://ampscript.guide/lookuporderedrowscs/',
625
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/lookuporderedrowscs/',
626
+ isConfirmed: true,
627
+ differsFromOfficialDocs: false,
628
+ minArgs: 5,
629
+ maxArgs: INF,
630
+ category: 'Data Extension',
631
+ description:
632
+ 'Case-sensitive version of LookupOrderedRows. Returns a sorted rowset of matching rows.',
633
+ params: [
634
+ {
635
+ name: 'dataExt',
636
+ description: 'The name of the data extension that contains the data to retrieve',
637
+ type: 'string',
638
+ },
639
+ {
640
+ name: 'numRows',
641
+ description:
642
+ 'The number of rows to return. A value less than 1 returns all rows (max 2,000)',
643
+ type: 'number',
644
+ },
645
+ {
646
+ name: 'sortColumn',
647
+ description:
648
+ 'The column to sort data by, followed by ASC or DESC (case-insensitive)',
649
+ type: 'string',
650
+ },
651
+ {
652
+ name: 'searchColumn1',
653
+ description: 'The name of the column to search',
654
+ type: 'string',
655
+ },
656
+ { name: 'searchValue1', description: 'The value that identifies the rows to retrieve' },
657
+ {
658
+ name: 'searchColumnN',
659
+ mcnSince: null,
660
+ mcnNotes: null,
661
+ description: 'Additional filter column',
662
+ type: 'string',
663
+ optional: true,
664
+ },
665
+ { name: 'searchValueN', description: 'Additional filter value', optional: true },
666
+ ],
667
+ returnType: 'rowset',
668
+ returnDescription: 'A case-sensitive, sorted, row-limited rowset of matching rows.',
669
+ repeat: [{ startIndex: 3, groupSize: 2, minGroups: 1 }],
670
+ syntax: 'LookupOrderedRowsCS(dataExt, numRows, sortColumn, searchColumn1, searchValue1[, searchColumnN, searchValueN, ...])',
671
+ example:
672
+ "%%[ SET @rows = LookupOrderedRowsCS('Orders', 5, 'OrderDate DESC', 'SubKey', _subscriberkey) ]%%",
673
+ },
674
+ {
675
+ name: 'LookupRows',
676
+ supportedInCloudPage: true,
677
+ supportedInEmail: true,
678
+ mcnSince: null,
679
+ handlebarsEquivalent: 'query',
680
+ handlebarsExact: false,
681
+ mcnNotes: null,
682
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-lookup-rows.html',
683
+ guideUrl: 'https://ampscript.guide/lookuprows/',
684
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/lookuprows/',
685
+ isConfirmed: true,
686
+ differsFromOfficialDocs: false,
687
+ minArgs: 3,
688
+ maxArgs: INF,
689
+ category: 'Data Extension',
690
+ description: 'Returns a rowset of all matching rows from a data extension.',
691
+ params: [
692
+ {
693
+ name: 'dataExt',
694
+ description: 'The name of the data extension that contains the data to retrieve',
695
+ type: 'string',
696
+ },
697
+ {
698
+ name: 'searchColumn1',
699
+ description: 'The name of the column to search',
700
+ type: 'string',
701
+ },
702
+ { name: 'searchValue1', description: 'The value that identifies the rows to retrieve' },
703
+ {
704
+ name: 'searchColumnN',
705
+ mcnSince: null,
706
+ mcnNotes: null,
707
+ description: 'Additional filter column',
708
+ type: 'string',
709
+ optional: true,
710
+ },
711
+ { name: 'searchValueN', description: 'Additional filter value', optional: true },
712
+ ],
713
+ returnType: 'rowset',
714
+ returnDescription: 'A rowset of all rows that match the search criteria.',
715
+ repeat: [{ startIndex: 1, groupSize: 2, minGroups: 1 }],
716
+ syntax: 'LookupRows(dataExt, searchColumn1, searchValue1[, searchColumnN, searchValueN, ...])',
717
+ example: "%%=LookupRows('MyDE', 'Status', 'Active')=%%",
718
+ },
719
+ {
720
+ name: 'LookupRowsCS',
721
+ supportedInCloudPage: true,
722
+ supportedInEmail: true,
723
+ mcnSince: null,
724
+ handlebarsEquivalent: 'query',
725
+ handlebarsExact: false,
726
+ mcnNotes: null,
727
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-lookup-rows-cs.html',
728
+ guideUrl: 'https://ampscript.guide/lookuprowscs/',
729
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/lookuprowscs/',
730
+ isConfirmed: true,
731
+ differsFromOfficialDocs: false,
732
+ minArgs: 3,
733
+ maxArgs: INF,
734
+ category: 'Data Extension',
735
+ description: 'Case-sensitive version of LookupRows. Returns a rowset of matching rows.',
736
+ params: [
737
+ {
738
+ name: 'dataExt',
739
+ description: 'The name of the data extension that contains the data to retrieve',
740
+ type: 'string',
741
+ },
742
+ {
743
+ name: 'searchColumn1',
744
+ description: 'The name of the column to search',
745
+ type: 'string',
746
+ },
747
+ { name: 'searchValue1', description: 'The value that identifies the rows to retrieve' },
748
+ {
749
+ name: 'searchColumnN',
750
+ mcnSince: null,
751
+ mcnNotes: null,
752
+ description: 'Additional filter column',
753
+ type: 'string',
754
+ optional: true,
755
+ },
756
+ { name: 'searchValueN', description: 'Additional filter value', optional: true },
757
+ ],
758
+ returnType: 'rowset',
759
+ returnDescription: 'A case-sensitive rowset of all rows that match the search criteria.',
760
+ repeat: [{ startIndex: 1, groupSize: 2, minGroups: 1 }],
761
+ syntax: 'LookupRowsCS(dataExt, searchColumn1, searchValue1[, searchColumnN, searchValueN, ...])',
762
+ example: "%%[ SET @rows = LookupRowsCS('Orders', 'SubKey', _subscriberkey) ]%%",
763
+ },
764
+ {
765
+ name: 'Row',
766
+ supportedInCloudPage: true,
767
+ supportedInEmail: true,
768
+ mcnSince: 67,
769
+ handlebarsEquivalent: 'get',
770
+ handlebarsExact: false,
771
+ mcnNotes: null,
772
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-row.html',
773
+ guideUrl: 'https://ampscript.guide/row/',
774
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/row/',
775
+ isConfirmed: true,
776
+ differsFromOfficialDocs: false,
777
+ minArgs: 2,
778
+ maxArgs: 2,
779
+ category: 'Data Extension',
780
+ description:
781
+ 'Returns a specific row from a rowset by its 1-based index. Index 0 (or any out-of-range index) aborts the page rather than returning an empty row.',
782
+ params: [
783
+ { name: 'rowset', description: 'Rowset to access', type: 'rowset' },
784
+ { name: 'rowIndex', description: '1-based row index', type: 'number' },
785
+ ],
786
+ returnType: 'row',
787
+ returnDescription: 'The row at the requested 1-based index within the rowset.',
788
+ syntax: 'Row(rowset, rowIndex)',
789
+ example: '%%=Row(@rows, 1)=%%',
790
+ },
791
+ {
792
+ name: 'RowCount',
793
+ supportedInCloudPage: true,
794
+ supportedInEmail: true,
795
+ mcnSince: 67,
796
+ handlebarsEquivalent: 'length',
797
+ handlebarsExact: false,
798
+ mcnNotes: null,
799
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-row-count.html',
800
+ guideUrl: 'https://ampscript.guide/rowcount/',
801
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/rowcount/',
802
+ isConfirmed: true,
803
+ differsFromOfficialDocs: false,
804
+ minArgs: 1,
805
+ maxArgs: 1,
806
+ category: 'Data Extension',
807
+ description: 'Returns the number of rows in a rowset.',
808
+ params: [{ name: 'rowset', description: 'Rowset to count', type: 'rowset' }],
809
+ returnType: 'number',
810
+ returnDescription: 'The number of rows in the rowset.',
811
+ syntax: 'RowCount(rowset)',
812
+ example: '%%=RowCount(@rows)=%%',
813
+ },
814
+ {
815
+ name: 'UpdateData',
816
+ supportedInCloudPage: true,
817
+ supportedInEmail: false,
818
+ mcnSince: null,
819
+ handlebarsEquivalent: null,
820
+ mcnNotes: null,
821
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-update-data.html',
822
+ guideUrl: 'https://ampscript.guide/updatedata/',
823
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/updatedata/',
824
+ isConfirmed: true,
825
+ differsFromOfficialDocs: true,
826
+ officialDocsNote:
827
+ 'Email/send-context finding: UpdateData is not valid in sendable email content. An isolated UpdateData(...) is rejected with HTTP 400 errorcode 10005 ("UpdateData Function is not valid in content. This function is only allowed in a non batch context."). A send is a batch operation, so the UpdateData/*Data write family cannot run inside a sendable email; use the UpdateDE variant instead, which the send parser accepts in sendable content. This is a CloudPage / landing-page (non-batch) feature.',
828
+ minArgs: 6,
829
+ maxArgs: INF,
830
+ category: 'Data Extension',
831
+ description:
832
+ 'Updates existing rows in a data extension that match the specified search columns. Returns the number of rows updated.',
833
+ params: [
834
+ {
835
+ name: 'dataExt',
836
+ description: 'The name of the data extension that contains the data to update',
837
+ type: 'string',
838
+ },
839
+ {
840
+ name: 'columnValuePairs',
841
+ description:
842
+ 'The number of column and value pairs for the function to match against',
843
+ type: 'number',
844
+ },
845
+ {
846
+ name: 'searchColumnName1',
847
+ description: 'The name of a column to search for the data to update',
848
+ type: 'string',
849
+ },
850
+ { name: 'searchValue1', description: 'The value that identifies the row to update' },
851
+ {
852
+ name: 'searchColumnNameN',
853
+ description: 'Additional search column name (count given by columnValuePairs)',
854
+ type: 'string',
855
+ optional: true,
856
+ },
857
+ {
858
+ name: 'searchValueN',
859
+ description: 'Additional search value (count given by columnValuePairs)',
860
+ optional: true,
861
+ },
862
+ {
863
+ name: 'columnToUpdate1',
864
+ description: 'The column that contains the data to update',
865
+ type: 'string',
866
+ },
867
+ { name: 'updatedValue1', description: 'The data to update in the specified column' },
868
+ {
869
+ name: 'columnToUpdateN',
870
+ description: 'Additional column to update',
871
+ type: 'string',
872
+ optional: true,
873
+ },
874
+ { name: 'updatedValueN', description: 'Additional value to update', optional: true },
875
+ ],
876
+ returnType: 'number',
877
+ returnDescription: 'The number of rows updated.',
878
+ repeat: [
879
+ { startIndex: 2, groupSize: 2, minGroups: 1, countParam: 'columnValuePairs' },
880
+ { startIndex: 4, groupSize: 2, minGroups: 1 },
881
+ ],
882
+ syntax: 'UpdateData(dataExt, columnValuePairs, searchColumnName1, searchValue1[, searchColumnNameN, searchValueN, ...], columnToUpdate1, updatedValue1[, columnToUpdateN, updatedValueN, ...])',
883
+ example:
884
+ "%%=UpdateData('Subscribers', 1, 'SubscriberKey', _subscriberkey, 'Status', 'Active')=%%",
885
+ },
886
+ {
887
+ name: 'UpdateDE',
888
+ supportedInCloudPage: true,
889
+ supportedInEmail: true,
890
+ mcnSince: null,
891
+ handlebarsEquivalent: null,
892
+ mcnNotes: null,
893
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-update-de.html',
894
+ guideUrl: 'https://ampscript.guide/updatede/',
895
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/updatede/',
896
+ isConfirmed: true,
897
+ differsFromOfficialDocs: false,
898
+ minArgs: 6,
899
+ maxArgs: INF,
900
+ category: 'Data Extension',
901
+ description:
902
+ 'Updates existing rows in a data extension. Email-context variant of UpdateData. Returns the number of rows updated.',
903
+ params: [
904
+ {
905
+ name: 'dataExt',
906
+ description: 'The name of the data extension that contains the data to update',
907
+ type: 'string',
908
+ },
909
+ {
910
+ name: 'columnValuePairs',
911
+ description:
912
+ 'The number of column and value pairs for the function to match against',
913
+ type: 'number',
914
+ },
915
+ {
916
+ name: 'searchColumnName1',
917
+ description: 'The name of a column to search for the data to update',
918
+ type: 'string',
919
+ },
920
+ { name: 'searchValue1', description: 'The value that identifies the row to update' },
921
+ {
922
+ name: 'searchColumnNameN',
923
+ description: 'Additional search column name (count given by columnValuePairs)',
924
+ type: 'string',
925
+ optional: true,
926
+ },
927
+ {
928
+ name: 'searchValueN',
929
+ description: 'Additional search value (count given by columnValuePairs)',
930
+ optional: true,
931
+ },
932
+ {
933
+ name: 'columnToUpdate1',
934
+ description: 'The column that contains the data to update',
935
+ type: 'string',
936
+ },
937
+ { name: 'updatedValue1', description: 'The data to update in the specified column' },
938
+ {
939
+ name: 'columnToUpdateN',
940
+ description: 'Additional column to update',
941
+ type: 'string',
942
+ optional: true,
943
+ },
944
+ { name: 'updatedValueN', description: 'Additional value to update', optional: true },
945
+ ],
946
+ returnType: 'number',
947
+ returnDescription: 'The number of rows updated.',
948
+ repeat: [
949
+ { startIndex: 2, groupSize: 2, minGroups: 1, countParam: 'columnValuePairs' },
950
+ { startIndex: 4, groupSize: 2, minGroups: 1 },
951
+ ],
952
+ syntax: 'UpdateDE(dataExt, columnValuePairs, searchColumnName1, searchValue1[, searchColumnNameN, searchValueN, ...], columnToUpdate1, updatedValue1[, columnToUpdateN, updatedValueN, ...])',
953
+ example:
954
+ "%%=UpdateDE('Subscribers', 1, 'SubscriberKey', _subscriberkey, 'Status', 'Active')=%%",
955
+ },
956
+ {
957
+ name: 'UpsertData',
958
+ supportedInCloudPage: true,
959
+ supportedInEmail: false,
960
+ mcnSince: null,
961
+ handlebarsEquivalent: null,
962
+ mcnNotes: null,
963
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-upsert-data.html',
964
+ guideUrl: 'https://ampscript.guide/upsertdata/',
965
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/upsertdata/',
966
+ isConfirmed: true,
967
+ differsFromOfficialDocs: true,
968
+ officialDocsNote:
969
+ 'Email/send-context finding: UpsertData is not valid in sendable email content. An isolated UpsertData(...) is rejected with HTTP 400 errorcode 10005 ("UpsertData Function is not valid in content. This function is only allowed in a non batch context."). A send is a batch operation, so the UpsertData/*Data write family cannot run inside a sendable email; use the UpsertDE variant instead, which the send parser accepts in sendable content. This is a CloudPage / landing-page (non-batch) feature.',
970
+ minArgs: 6,
971
+ maxArgs: INF,
972
+ category: 'Data Extension',
973
+ description:
974
+ 'Updates a row in a data extension if matching columns and values are found, or inserts a row if no matches are found. Returns the number of rows affected.',
975
+ params: [
976
+ {
977
+ name: 'dataExt',
978
+ description: 'The name of the data extension to update or insert data into',
979
+ type: 'string',
980
+ },
981
+ {
982
+ name: 'columnValuePairs',
983
+ description:
984
+ 'The number of column and value pairs for the function to match against',
985
+ type: 'number',
986
+ },
987
+ {
988
+ name: 'searchColumnName1',
989
+ description: 'The name of the column to search',
990
+ type: 'string',
991
+ },
992
+ {
993
+ name: 'searchValue1',
994
+ description: 'The value that identifies the row to update or insert',
995
+ },
996
+ {
997
+ name: 'searchColumnNameN',
998
+ description: 'Additional search column name (count given by columnValuePairs)',
999
+ type: 'string',
1000
+ optional: true,
1001
+ },
1002
+ {
1003
+ name: 'searchValueN',
1004
+ description: 'Additional search value (count given by columnValuePairs)',
1005
+ optional: true,
1006
+ },
1007
+ {
1008
+ name: 'columnToUpsert1',
1009
+ description: 'The column to update or insert data into',
1010
+ type: 'string',
1011
+ },
1012
+ {
1013
+ name: 'upsertedValue1',
1014
+ description: 'The value to update or insert into the specified column',
1015
+ },
1016
+ {
1017
+ name: 'columnToUpsertN',
1018
+ description: 'Additional column to update or insert',
1019
+ type: 'string',
1020
+ optional: true,
1021
+ },
1022
+ {
1023
+ name: 'upsertedValueN',
1024
+ description: 'Additional value to update or insert',
1025
+ optional: true,
1026
+ },
1027
+ ],
1028
+ returnType: 'number',
1029
+ returnDescription: 'The number of rows inserted or updated.',
1030
+ repeat: [
1031
+ { startIndex: 2, groupSize: 2, minGroups: 1, countParam: 'columnValuePairs' },
1032
+ { startIndex: 4, groupSize: 2, minGroups: 1 },
1033
+ ],
1034
+ syntax: 'UpsertData(dataExt, columnValuePairs, searchColumnName1, searchValue1[, searchColumnNameN, searchValueN, ...], columnToUpsert1, upsertedValue1[, columnToUpsertN, upsertedValueN, ...])',
1035
+ example:
1036
+ "%%=UpsertData('Subscribers', 1, 'SubscriberKey', _subscriberkey, 'Status', 'Active')=%%",
1037
+ },
1038
+ {
1039
+ name: 'UpsertDE',
1040
+ supportedInCloudPage: true,
1041
+ supportedInEmail: true,
1042
+ mcnSince: null,
1043
+ handlebarsEquivalent: null,
1044
+ mcnNotes: null,
1045
+ docUrl: 'https://developer.salesforce.com/docs/marketing/marketing-cloud-ampscript/references/mc-ampscript-data-extension/mc-ampscript-reference-data-extension-upsert-de.html',
1046
+ guideUrl: 'https://ampscript.guide/upsertde/',
1047
+ sfmcGuideUrl: 'https://sfmc.guide/engagement/ampscript/functions/upsertde/',
1048
+ isConfirmed: true,
1049
+ differsFromOfficialDocs: false,
1050
+ minArgs: 6,
1051
+ maxArgs: INF,
1052
+ category: 'Data Extension',
1053
+ description:
1054
+ 'Updates or inserts a row in a data extension. Email-context variant of UpsertData. Returns the number of rows affected.',
1055
+ params: [
1056
+ {
1057
+ name: 'dataExt',
1058
+ description: 'The name of the data extension to update or insert data into',
1059
+ type: 'string',
1060
+ },
1061
+ {
1062
+ name: 'columnValuePairs',
1063
+ description:
1064
+ 'The number of column and value pairs for the function to match against',
1065
+ type: 'number',
1066
+ },
1067
+ {
1068
+ name: 'searchColumnName1',
1069
+ description: 'The name of the column to search',
1070
+ type: 'string',
1071
+ },
1072
+ {
1073
+ name: 'searchValue1',
1074
+ description: 'The value that identifies the row to update or insert',
1075
+ },
1076
+ {
1077
+ name: 'searchColumnNameN',
1078
+ description: 'Additional search column name (count given by columnValuePairs)',
1079
+ type: 'string',
1080
+ optional: true,
1081
+ },
1082
+ {
1083
+ name: 'searchValueN',
1084
+ description: 'Additional search value (count given by columnValuePairs)',
1085
+ optional: true,
1086
+ },
1087
+ {
1088
+ name: 'columnToUpsert1',
1089
+ description: 'The column to update or insert data into',
1090
+ type: 'string',
1091
+ },
1092
+ {
1093
+ name: 'upsertedValue1',
1094
+ description: 'The value to update or insert into the specified column',
1095
+ },
1096
+ {
1097
+ name: 'columnToUpsertN',
1098
+ description: 'Additional column to update or insert',
1099
+ type: 'string',
1100
+ optional: true,
1101
+ },
1102
+ {
1103
+ name: 'upsertedValueN',
1104
+ description: 'Additional value to update or insert',
1105
+ optional: true,
1106
+ },
1107
+ ],
1108
+ returnType: 'number',
1109
+ returnDescription: 'The number of rows inserted or updated.',
1110
+ repeat: [
1111
+ { startIndex: 2, groupSize: 2, minGroups: 1, countParam: 'columnValuePairs' },
1112
+ { startIndex: 4, groupSize: 2, minGroups: 1 },
1113
+ ],
1114
+ syntax: 'UpsertDE(dataExt, columnValuePairs, searchColumnName1, searchValue1[, searchColumnNameN, searchValueN, ...], columnToUpsert1, upsertedValue1[, columnToUpsertN, upsertedValueN, ...])',
1115
+ example:
1116
+ "%%=UpsertDE('Subscribers', 1, 'SubscriberKey', _subscriberkey, 'Status', 'Active')=%%",
1117
+ },
1118
+ ];