Skip to content

getData() Contract ​

The getData() function is how AddMaple widgets access your data. You implement this function and pass it to the embed component.

Overview ​

getData() is an async function that returns:

  • Dataset metadata (columns, row count)
  • Preview rows for browser-mode analysis
  • Optional serverFetch URL for full server-mode analysis

The embed calls getData() once on mount and again before server-mode analysis if needed.

Response Schema ​

json
{
  "datasetId": "dataset_123",
  "datasetType": "survey",
  "n_rows": 512,
  "columns": [
    { "name": "satisfaction", "type": "numeric" },
    { "name": "age", "type": "numeric" },
    { "name": "comment", "type": "text" },
    { "name": "would_recommend", "type": "boolean" }
  ],
  "previewRows": [
    { "satisfaction": "8", "age": "34", "comment": "Loved it", "would_recommend": "true" },
    { "satisfaction": "6", "age": "28", "comment": "Good but slow", "would_recommend": "true" }
  ],
  "serverFetch": {
    "url": "https://partner.example.com/addmaple/full-data/tf_123",
    "method": "GET",
    "headers": { "Authorization": "Bearer abc123" },
    "expiresAt": "2025-12-01T11:15:00Z"
  }
}

Field Reference ​

Required Fields ​

FieldTypeDescription
datasetIdstringUnique dataset identifier
columnsarrayColumn definitions with name and type
previewRowsarraySample rows for browser-mode analysis

Optional Fields ​

FieldTypeDescription
datasetTypestringHint about data source (e.g., survey, crm, support)
n_rowsnumberTotal row count in full dataset
serverFetchobjectURL for AddMaple to fetch full dataset

Column Types ​

TypeDescription
numericNumbers, percentages, currencies
categoryCategorical/enum values
textFree-form text responses
booleanTrue/false values

serverFetch Object ​

FieldTypeDescription
urlstringRequired. URL AddMaple will call for full data
methodstringHTTP method (default: GET)
headersobjectOptional headers to include
expiresAtstringISO timestamp when URL expires

Implementation Examples ​

Basic: Server-Backed getData() ​

The recommended approach — your server fetches data and returns the response:

js
async function getData() {
  const res = await fetch('/api/addmaple/get-embed-data?datasetId=dataset_123', {
    credentials: 'include'
  })
  if (!res.ok) throw new Error('Failed to get data')
  return res.json()
}
js
// Express.js example
app.get('/api/addmaple/get-embed-data', async (req, res) => {
  const { datasetId } = req.query
  
  // Fetch data from your source (SaaS API, database, etc.)
  const rows = await fetchSourceRows(datasetId)
  
  // Create preview (sanitize PII if needed)
  const preview = rows.slice(0, 150)
  
  // Optionally create a signed URL for full data access
  const serverFetch = await createSignedUrl(datasetId)
  
  res.json({
    datasetId,
    datasetType: 'survey',
    n_rows: rows.length,
    columns: detectColumns(rows),
    previewRows: preview,
    serverFetch
  })
})

With Signed URL (S3 Presigned) ​

For large datasets, provide a presigned S3 URL:

js
app.get('/api/addmaple/get-embed-data', async (req, res) => {
  const { datasetId } = req.query
  
  // Generate presigned S3 URL (expires in 15 minutes)
  const presignedUrl = await s3.getSignedUrl('getObject', {
    Bucket: 'my-data-bucket',
    Key: `datasets/${datasetId}.csv`,
    Expires: 900
  })
  
  res.json({
    datasetId,
    columns: await getColumnSchema(datasetId),
    previewRows: await getPreviewRows(datasetId, 150),
    serverFetch: {
      url: presignedUrl,
      method: 'GET',
      expiresAt: new Date(Date.now() + 900000).toISOString()
    }
  })
})

Without serverFetch (Browser-Only) ​

If you don't provide serverFetch, only browser-mode analysis is available:

js
async function getData() {
  return {
    datasetId: 'local_dataset',
    columns: [
      { name: 'score', type: 'numeric' },
      { name: 'category', type: 'category' }
    ],
    previewRows: myLocalData.slice(0, 200)
    // No serverFetch — browser-mode only
  }
}

Browser Mode Limitations

Without serverFetch:

  • Only heuristic analysis on preview rows
  • AI Chat is unavailable
  • Lower fidelity results for large datasets

Best Practices ​

Preview Rows ​

  • Include 100-200 rows for good browser-mode results
  • Sanitize PII unless user has consented
  • Include a representative sample (not just the first N rows)

Columns ​

  • Always include name and type for each column
  • Use accurate types — this affects analysis quality
  • Include all columns the user might want to analyze

serverFetch URLs ​

  • Use short-lived URLs (15-60 minutes)
  • Prefer presigned URLs over embedding credentials
  • Consider IP allowlisting for partner endpoints
  • Return data in CSV or JSON format

Error Handling ​

If getData() throws or returns invalid data, the embed will:

  1. Emit a getData_error analytics event
  2. Show an error state to the user
  3. Not attempt server-mode analysis
js
async function getData() {
  try {
    const res = await fetch('/api/data')
    if (!res.ok) throw new Error(`HTTP ${res.status}`)
    return res.json()
  } catch (error) {
    // Log error to your system
    console.error('getData failed:', error)
    throw error // Re-throw so embed knows it failed
  }
}

Partner Documentation