# Update Analytics Data Source Change one of the creator's data sources. Only what you send changes. Changing what it fetches (the app, action, connection, arguments, options or query of a sync or live source; the inputs or code of a merge; the rows of a fixed source) saves it and fetches again, and the panels that read it follow. Changing how it is kept (name, description, date keys, schedule, a spreadsheet's options, incremental refreshes) fetches nothing. Incremental refreshes fetch only changed records between full refreshes; they stay off until you send incrementalDetails with status active, which are checked against the stored rows and the app first, and isIncrementalEnabled true. A change that reaches published embeds asks you to confirm it first: see confirmationReceipt. `PUT https://connect.mindcloud.co/v2/analytics/data-sources/:dataSourceId` Permissions: `analytics:page:create`. ## Parameters ### Path - `dataSourceId` (string, required): The data source id, from List Analytics Data Sources. ### Headers - `X-Company-Id` (string): Optional. The id of the organization to act in. Leave it out to act in the API key's own organization. Here a key acts in another organization only as one of its members: with "Use this key across all of your organizations" on, in an organization its creator belongs to with a role. Child organizations and MindCloud staff access do not reach this endpoint. Every response's X-Company-Id header names the organization it acted in. See [Organizations](https://mindcloud.co/docs/api/rest/introduction/organizations). ### Body - `name` (string): A new name. A name for the source. Left out, one is written from what it fetches. - `description` (string): A new description, or null to clear it. What the data holds, in a sentence. Left out, one is written from the data. - `app` (string): A sync or live source: another app, by id or slug. The app to fetch from, by id or slug, from List Universal Apps. - `action` (string): A sync or live source: another read action, by id or slug. The app's read action, by id or slug, from List Universal Actions. - `connectionId` (string): A sync or live source: another connection, from List Connections. The connection to fetch with, from List Connections. - `arguments` (object): A sync or live source: the arguments, replacing them all. The action's arguments, { argumentKey: value }, as Get Universal Action lists them. Values may use date expressions such as {{now-2y}}. - `options` (object): A sync or live source: the options, replacing them all. The action's options, such as { "pagination": { "mode": "all" } }. - `query` (object): A sync or live source: the filter and sort, or null to remove them. A filter and sort the app applies before the rows are stored. The action must support them exactly, or the request is refused. - `filter` (any): The filter the app applies, as Get Universal Action describes it. Values must be literals. - `sort` (any): The sort the app applies. - `dataSources` (array): A merge: its inputs, replacing them all. For a merge source: the sources it combines. - `dataSourceId` (string, required): The input source, a sync or fixed source of yours, from List Analytics Data Sources. - `alias` (string, required): The name the merge SQL and code read this input by. - `query` (string): SQL that shapes this input before the merge, reading it as `src`. Leave it out to use the input as is. - `transformCode` (string): A merge: its code. For a merge source: JavaScript that receives each input by its alias and returns the combined rows. Required when there is more than one input. - `rows` (array): A fixed source: rows that replace its data. To change some rows, use Update Analytics Data Source Table. For a fixed source: the rows, as objects with the same keys, up to 1000. They replace the source's data. - `dateKeys` (object): Which columns hold dates, or null to have them worked out from the data again. Which columns hold dates, for page date filters. Left out (or null on update), they are worked out from the data after each refresh. - `primaryDateKey` (string): The column page date filters use. - `primaryDateKeyGrain` (string): That column's grain, such as day or month. - `createdDateKey` (string): The column holding when each record was created. - `updatedDateKey` (string): The column holding when each record last changed. - `hasNoDates` (boolean): True when the source has no date column. - `sheetName` (string): A fixed source from a spreadsheet: the sheet to read. For a fixed source made from a spreadsheet file: the sheet to read. - `useHeader` (boolean): A fixed source from a spreadsheet: whether the first row holds the column names. For a fixed source made from a spreadsheet file: whether its first row holds the column names. - `removeTopRows` (number): A fixed source from a spreadsheet: rows above the header to skip. For a fixed source made from a spreadsheet file: how many rows above the header to skip. - `refreshIntervalSeconds` (number): A sync or merge source: how often it refreshes in full, in seconds. How often a sync or merge source refreshes in full, in seconds, up to 604800. A source that takes long to fetch may be held to a longer interval; the answer says what was set. - `isIncrementalEnabled` (boolean): A sync source: switch incremental refreshes on or off. For a sync source: switch incremental refreshes on or off. On needs incremental details whose status is active, saved now or before. - `incrementalIntervalSeconds` (number): A sync source: how often incremental refreshes run, in seconds. For a sync source: how often incremental refreshes run, in seconds. Held between the shortest and longest the app allows, and shorter than the full refresh. - `incrementalDetails` (object): A sync source: how it fetches only changed records. How this sync source fetches only changed records. Setting status active checks the dedupKey and sinceArguments against the stored rows and the app first, and saves nothing if they fail. - `status` (string): Whether this source can fetch only changed records: active or unavailable. Allowed values: - `active`: This source can fetch only changed records. - `unavailable`: It cannot. - `dedupKey` (array of strings): The field paths that identify a record, such as ["id"]. - `sinceArguments` (object): The extra action arguments that ask the app for records changed since the last check, keyed like the source's arguments, such as { "updatedAfter": "{{since}}" }. - `catches` (string): What the change check finds: newAndChanged or newOnly. Left out, it is measured. Allowed values: - `newAndChanged`: The check finds new and edited records. - `newOnly`: It finds new records only. - `overlapSeconds` (number): How far back before the last check each check looks, in seconds: one of 300, 900, 1800, 3600, 7200, 21600. - `confirmationReceipt` (string): The receipt a 409 ANALYTICS_EMBED_CONFIRMATION_REQUIRED answered, to confirm the change to published embeds. Only after a 409 ANALYTICS_EMBED_CONFIRMATION_REQUIRED for the same request: the confirmationReceipt from its error.details, confirming the change to the published embeds it lists. ## Example request ```bash curl --request PUT \ --url 'https://connect.mindcloud.co/v2/analytics/data-sources/Ds3Hq9Lp2WxM' \ --header 'Authorization: Bearer $MINDCLOUD_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "name": "Open deals", "description": "Every open deal with its owner and amount.", "connectionId": "Cn6vH3jW8qYt", "arguments": { "createdAfter": "{{now-1y}}" }, "dateKeys": { "primaryDateKey": "createdAt" }, "refreshIntervalSeconds": 86400, "isIncrementalEnabled": false, "confirmationReceipt": "eyJmaW5nZXJwcmludCI6IjhkNGMifQ" }' ``` ## Response fields - `id` (string): The data source's id. - `name` (string): The data source's name. - `description` (string): What the data holds, in a sentence. - `createdBy` (string): The userId of the member who created it, from List Members: the key's creator for their own sources. - `type` (string): sync: fetched from an app action on a schedule and stored; live: fetched from an app action when a drill-down opens, with its values, and never stored; merge: combines other sources with SQL and code; fixed: rows you supply, never refetched. Allowed values: - `sync` - `live` - `merge` - `fixed` - `appId` (string): The app a sync or live source fetches from, from List Universal Apps. Null for merge and fixed sources. - `actionId` (string): The app action it fetches with, from List Universal Actions. Null for merge and fixed sources. - `actionName` (string): The app action's name. - `connectionId` (string): The connection it fetches with, from List Connections. Null for merge and fixed sources. - `status` (string): Where its data stands. live: a live source, which has no stored data; neverFetched: no fetch has run yet; noData: a fixed source with no rows yet; draft: waiting for its first fetch; queued: a fetch is waiting to start; refreshing: a fetch is running; ready: its rows are stored; empty: the last fetch returned no rows; failed: the last fetch failed (see message). Allowed values: - `live` - `neverFetched` - `noData` - `draft` - `queued` - `refreshing` - `ready` - `empty` - `failed` - `rowCount` (number): How many rows the last fetch stored. - `fetchedOn` (date): When the stored rows were fetched. - `message` (string): Why the last fetch failed, when it did. - `refreshIntervalSeconds` (number): How often a sync or merge source refreshes in full, in seconds. Null for live and fixed sources. - `isIncrementalEnabled` (boolean): For a sync source, whether incremental refreshes (fetching only changed records between full refreshes) are switched on. Null for other types. - `incrementalIntervalSeconds` (number): How often incremental refreshes run, in seconds, while they run. Null otherwise. - `isPaused` (boolean): True when every page that uses it is paused or deleted, so its scheduled refresh is skipped. - `panelCount` (number): How many panels on its owner's pages read it. - `isUnused` (boolean): True when no panel reads it and it has not changed for a day: the sources the app's cleanup offers to delete. - `createdOn` (date): When it was created. - `updatedOn` (date): When it last changed. - `appVersion` (string): The app version a sync or live source is pinned to. - `latestAppVersion` (string): The app's current published version, when the source is pinned to an older one. Null when it is current. - `arguments` (object): The action's arguments, as stored: each value in its stored form. Send them back as they are, or as plain values. Null for merge and fixed sources. - `options` (object): The action's options, such as pagination. Null for merge and fixed sources. - `query` (object): The filter and sort the app applies before the rows are stored: { filter, sort }. Null when there is none. - `inputs` (array of objects): For a merge source, the sources it combines. Null for other types. - `dataSourceId` (string): The input source, from List Analytics Data Sources. - `alias` (string): The name the merge SQL and code read this input by. - `query` (string): The SQL that shapes this input, reading it as `src`. Empty when it is used as is. - `transformCode` (string): For a merge source, the code that combines its inputs. Null for other types. - `file` (object): For a fixed source, the data it holds. Null for other types, or before any data is stored. - `origin` (string): Where the rows came from. rows: rows sent in a request; attachment: an uploaded file; tableEditor: an edit to the table. Allowed values: - `rows` - `attachment` - `tableEditor` - `filename` (string): The file's name, or the label given to rows sent in a request. - `format` (string): The file format, such as csv, xlsx or json. - `mimeType` (string): The file's media type. - `sizeBytes` (number): The size of the stored data in bytes. - `uploadedOn` (date): When the data was stored. - `rowCount` (number): How many rows the data holds. - `sheetName` (string): For a spreadsheet, the sheet the rows are read from. - `useHeader` (boolean): For a spreadsheet, whether its first row holds the column names. - `removeTopRows` (number): For a spreadsheet, how many rows above the header are skipped. - `dateKeys` (object): Which columns hold dates, for page date filters. Null until they are known. - `primaryDateKey` (string): The column page date filters use for this source. - `primaryDateKeyGrain` (string): The primary date column's grain: day for dates, timestamp for dates with times. - `createdDateKey` (string): The column holding when each record was created. - `updatedDateKey` (string): The column holding when each record last changed. - `hasNoDates` (boolean): True when the source has no date column. - `isIncrementalActive` (boolean): For a sync source, whether incremental refreshes actually run: switched on, and the source can fetch only changed records. Null for other types. - `incremental` (object): For a sync source, how it fetches only changed records. Null when that was never set up. - `status` (string): Whether this source can fetch only changed records. active: it can; unavailable: it cannot. Allowed values: - `active` - `unavailable` - `dedupKey` (array): The field paths that identify a record, used to replace changed records. - `sinceArguments` (object): The extra action arguments that ask the app for records changed since the last check. - `catches` (string): What the change check finds. newAndChanged: new and edited records; newOnly: new records only. Allowed values: - `newAndChanged` - `newOnly` - `overlapSeconds` (number): How far back before the last check each check looks, in seconds. - `reason` (string): Why changed records cannot be fetched, when status is unavailable. - `checkedOn` (date): When these details were last checked against the source. - `coverage` (object): For a sync source, how much time its stored rows span. Null when not measured. - `code` (string): The coverage verdict, such as COVERED, TRUNCATED or FILTER_NOT_APPLIED. - `level` (string): How the verdict reads: ok, info or warn. Allowed values: - `ok` - `info` - `warn` - `message` (string): The verdict in words. - `coverageFrom` (date): The earliest record date the data holds. - `coverageTo` (date): The latest record date the data holds.