1"use strict";(globalThis.webpackChunkcheck_flow_docs||=[]).push([[4818],{7886(e,d,t){t.r(d),t.d(d,{assets:()=>c,contentTitle:()=>l,default:()=>o,frontMatter:()=>n,metadata:()=>s,toc:()=>a});const s=JSON.parse('{"id":"mcp/tools-data-sets","title":"Data Set Tools","description":"The MCP tools an AI client uses to read and manage Data Sets \u2014 their fields, records and saved views \u2014 and to import and export them as CSV.","source":"@site/docs/mcp/tools-data-sets.md","sourceDirName":"mcp","slug":"/mcp/tools-data-sets","permalink":"/docs/mcp/tools-data-sets","draft":false,"unlisted":false,"tags":[],"version":"current","lastUpdatedAt":1790595137000,"frontMatter":{"id":"tools-data-sets","title":"Data Set Tools","sidebar_label":"Data Set Tools","description":"The MCP tools an AI client uses to read and manage Data Sets \u2014 their fields, records and saved views \u2014 and to import and export them as CSV."},"sidebar":"docs","previous":{"title":"Template Tools","permalink":"/docs/mcp/tools-templates"},"next":{"title":"Schedule Tools","permalink":"/docs/mcp/tools-schedules"}}');var r=t(4848),i=t(8453);const n={id:"tools-data-sets",title:"Data Set Tools",sidebar_label:"Data Set Tools",description:"The MCP tools an AI client uses to read and manage Data Sets \u2014 their fields, records and saved views \u2014 and to import and export them as CSV."},l=void 0,c={},a=[{value:"How to Read This Page",id:"how-to-read-this-page",level:2},{value:"Tool Summary",id:"tool-summary",level:2},{value:"<code>list_data_sets</code>",id:"list_data_sets",level:2},{value:"<code>get_data_set</code>
1",id:"get_data_set",level:2},{value:"<code>create_data_set</code>",id:"create_data_set",level:2},{value:"<code>update_data_set</code>",id:"update_data_set",level:2},{value:"<code>delete_data_set</code>",id:"delete_data_set",level:2},{value:"<code>list_data_set_connections</code>",id:"list_data_set_connections",level:2},{value:"<code>create_data_set_field</code>",id:"create_data_set_field",level:2},{value:"<code>update_data_set_field</code>",id:"update_data_set_field",level:2},{value:"<code>delete_data_set_field</code>",id:"delete_data_set_field",level:2},{value:"<code>list_data_set_records</code>",id:"list_data_set_records",level:2},{value:"<code>get_data_set_record</code>",id:"get_data_set_record",level:2},{value:"<code>create_data_set_record</code>",id:"create_data_set_record",level:2},{value:"<code>update_data_set_record</code>",id:"update_data_set_record",level:2},{value:"<code>create_data_set_records</code>",id:"create_data_set_records",level:2},{value:"<code>delete_data_set_records</code>",id:"delete_data_set_records",level:2},{value:"<code>create_data_set_view</code>",id:"create_data_set_view",level:2},{value:"<code>update_data_set_view</code>",id:"update_data_set_view",level:2},{value:"<code>delete_data_set_view</code>",id:"delete_data_set_view",level:2},{value:"<code>create_data_set_from_csv</code>
1",id:"create_data_set_from_csv",level:2},{value:"<code>replace_data_set_records_from_csv</code>",id:"replace_data_set_records_from_csv",level:2},{value:"<code>export_data_set_csv</code>",id:"export_data_set_csv",level:2},{value:"Related Pages",id:"related-pages",level:2}];function h(e){const d={a:"a",admonition:"admonition",code:"code",h2:"h2",li:"li",p:"p",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,i.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsxs)(d.p,{children:["These tools let an AI client work with your workspace's ",(0,r.jsx)(d.a,{href:"/docs/data-sets/overview",children:"Data Sets"}),": the reference tables a template's Dropdown, Multi-Choice, Sub-Tasks or Table field can read its options from. A Data Set is made of fields (its columns), records (its rows) and saved ",(0,r.jsx)(d.a,{href:"/docs/data-sets/views",children:"views"}),", and a template field is linked to a view rather than to the Data Set as a whole. The tools mirror the ",(0,r.jsx)(d.a,{href:"/docs/api-v3/data-sets",children:"Data Sets"})," REST routes."]}),"\n",(0,r.jsxs)(d.p,{children:["Every tool that takes ",(0,r.jsx)(d.code,{children:"dataSetKey"})," accepts a Data Set's key or, for one of the ten ",(0,r.jsx)(d.a,{href:"/docs/data-sets/system-data-sets",children:"built-in System Data Sets"}),", its slug \u2014 ",(0,r.jsx)(d.code,{children:"system-countries"})," reaches the same Data Set as its key, in every workspace. Because a slug is a perfectly good name, a value that names nothing is refused with ",(0,r.jsx)(d.code,{children:"DATA_SET_NOT_FOUND"})," rather than as malformed. The built-in Data Sets can be read and exported but not written to; a write to one is refused with ",(0,r.jsx)(d.code,{children:"FORBIDDEN"}),"."]}),"\n",(0,r.jsxs)(d.p,{children:["Record cells are addressed by field name \u2014 ",(0,r.jsx)(d.code,{children:'{"Supplier": "Northwind Ltd"}'})," \u2014 or by field key. A name or key that matches no field of the Data Set is refused, naming the cell, rather than silently dropped."]}),"\n",(0,r.jsx)(d.h2,{id:"how-to-read-this-page",children:"How to Read This Page"}),"\n",(0,r.jsxs)(d.p,{children:["Every tool acts on the workspace your API key belongs to, as the member (or the workspace) the key acts as. There is no workspace argument. See ",(0,r.jsx)(d.a,{href:"/docs/mcp/connecting",children:"Connecting"}),"."]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsx)(d.li,{children:"The Read/Write column in the summary table says whether a tool can change anything."}),"\n",(0,r.jsxs)(d.li,{children:["Annotations are the hints a tool publishes to your client: ",(0,r.jsx)(d.code,{children:"readOnlyHint"}),", ",(0,r.jsx)(d.code,{children:"destructiveHint"})," and ",(0,r.jsx)(d.code,{children:"idempotentHint"}),". A hint a tool does not declare is left out of its definition, and the MCP specification tells a client to assume the cautious default in that case \u2014 that the tool may write, may be destructive and is not idempotent. See ",(0,r.jsx)(d.a,{href:"/docs/mcp/how-it-works#tool-annotations",children:"Tool Annotations"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:[(0,r.jsx)(d.code,{children:"idempotencyKey"})," appears on the write tools that accept it. It is optional and at most 255 characters. If a call times out or its answer is lost, send it again with the same key and the same arguments: the first call's answer comes back, marked ",(0,r.jsx)(d.code,{children:"checkflow.io/idempotentReplay"})," in the result's ",(0,r.jsx)(d.code,{children:"_meta"}),", instead of the work happening twice. The same key with different arguments is refused with ",(0,r.jsx)(d.code,{children:"CONFLICT"}),", and so is a retry while the first call is still running. See ",(0,r.jsx)(d.a,{href:"/docs/api-v3/idempotency",children:"Idempotency"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:["Refusals come back as an ordinary tool result with ",(0,r.jsx)(d.code,{children:"isError"})," set. ",(0,r.jsx)(d.code,{children:"structuredContent"})," carries the v3 error body \u2014 ",(0,r.jsx)(d.code,{children:"code"}),", ",(0,r.jsx)(d.code,{children:"message"}),", ",(0,r.jsx)(d.code,{children:"requestId"})," and ",(0,r.jsx)(d.code,{children:"field"})," \u2014 and the text block summarises it. See ",(0,r.jsx)(d.a,{href:"/docs/api-v3/errors",children:"Errors"})," and ",(0,r.jsx)(d.a,{href:"/docs/mcp/how-it-works#errors",children:"How It Works"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:["A tool that returns nothing, such as a delete, answers with a result that is not flagged ",(0,r.jsx)(d.code,{children:"isError"})," and carries no data."]}),"\n"]}),"\n",(0,r.jsxs)(d.p,{children:["Four REST routes have no tool: listing fields, listing views and reading one view are covered by ",(0,r.jsx)(d.code,{children:"get_data_set"}),", which returns every field and view in full, and deleting a single record
1is ",(0,r.jsx)(d.code,{children:"delete_data_set_records"})," with one key."]}),"\n",(0,r.jsx)(d.h2,{id:"tool-summary",children:"Tool Summary"}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Tool"}),(0,r.jsx)(d.th,{children:"What it does"}),(0,r.jsx)(d.th,{children:"Read/Write"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#list_data_sets",children:(0,r.jsx)(d.code,{children:"list_data_sets"})})}),(0,r.jsx)(d.td,{children:"Lists the workspace's Data Sets and the built-in ones"}),(0,r.jsx)(d.td,{children:"Read"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#get_data_set",children:(0,r.jsx)(d.code,{children:"get_data_set"})})}),(0,r.jsx)(d.td,{children:"Returns one Data Set with its fields and views"}),(0,r.jsx)(d.td,{children:"Read"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#create_data_set",children:(0,r.jsx)(d.code,{children:"create_data_set"})})}),(0,r.jsx)(d.td,{children:"Creates a Data Set"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#update_data_set",children:(0,r.jsx)(d.code,{children:"update_data_set"})})}),(0,r.jsx)(d.td,{children:"Renames or re-describes a Data Set"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#delete_data_set",children:(0,r.jsx)(d.code,{children:"delete_data_set"})})}),(0,r.jsx)(d.td,{children:"Deletes a Data Set"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#list_data_set_connections",children:(0,r.jsx)(d.code,{children:"list_data_set_connections"})})}),(0,r.jsx)(d.td,{children:"Lists the template fields that read from a Data Set"}),(0,r.jsx)(d.td,{children:"Read"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#create_data_set_field",children:(0,r.jsx)(d.code,{children:"create_data_set_field"})})}),(0,r.jsx)(d.td,{children:"Adds a field"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#update_data_set_field",children:(0,r.jsx)(d.code,{children:"update_data_set_field"})})}),(0,r.jsx)(d.td,{children:"Renames, retypes or re-describes a field"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#delete_data_set_field",children:(0,r.jsx)(d.code,{children:"delete_data_set_field"})})}),(0,r.jsx)(d.td,{children:"Deletes a field and every value in it"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#list_data_set_records",children:(0,r.jsx)(d.code,{children:"list_data_set_records"})})}),(0,r.jsx)(d.td,{children:"Lists records, optionally through a view"}),(0,r.jsx)(d.td,{children:"Read"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#get_data_set_record",children:(0,r.jsx)(d.code,{children:"get_data_set_record"})})}),(0,r.jsx)(d.td,{children:"Returns one record"}),(0,r.jsx)(d.td,{children:"Read"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#create_data_set_record",children:(0,r.jsx)(d.code,{children:"create_data_set_record"})})}),(0,r.jsx)(d.td,{children:"Adds one record and fires a webhook for it"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#update_data_set_record",children:(0,r.jsx)(d.code,{children:"update_data_set_record"})})}),(0,r.jsx)(d.td,{children:"Changes cells of one record"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#create_data_set_records",children:(0,r.jsx)(d.code,{children:"create_data_set_records"})})}),(0,r.jsx)(d.td,{children:"Appends or replaces up to 1,000 records"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#delete_data_set_records",children:(0,r.jsx)(d.code,{children:"delete_data_set_records"})})}),(0,r.jsx)(d.td,{children:"Deletes up to 1,000 records by key"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#create_data_set_view",children:(0,r.jsx)(d.code,{children:"create_data_set_view"})})}),(0,r.jsx)(d.td,{children:"Creates a saved view"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#update_data_set_view",children:(0,r.jsx)(d.code,{children:"update_data_set_view"})})}),(0,r.jsx)(d.td,{children:"Changes a saved view"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#delete_data_set_view",children:(0,r.jsx)(d.code,{children:"delete_data_set_view"})})}),(0,r.jsx)(d.td,{children:"Deletes a saved view"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#create_data_set_from_csv",children:(0,r.jsx)(d.code,{children:"create_data_set_from_csv"})})}),(0,r.jsx)(d.td,{children:"Creates a Data Set from CSV text"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#replace_data_set_records_from_csv",children:(0,r.jsx)(d.code,{children:"replace_data_set_records_from_csv"})})}),(0,r.jsx)(d.td,{children:"Replaces every record from CSV text"}),(0,r.jsx)(d.td,{children:"Write"})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.a,{href:"#export_data_set_csv",children:(0,r.jsx)(d.code,{children:"export_data_set_csv"})})}),(0,r.jsx)(d.td,{children:"Returns a Data Set's records as CSV text"}),(0,r.jsx)(d.td,{children:"Read"})]})]})]}),"\n",(0,r.jsx)(d.h2,{id:"list_data_sets",children:(0,r.jsx)(d.code,{children:"list_data_sets"})}),"\n",(0,r.jsx)(d.p,{children:"Lists the workspace's Data Sets, with the ten built-in ones appended. The description tells the model to start here before writing a template that offers a choice, because a drop-down is linked to a Data Set view rather than to a list of words. All of them come back at once \u2014 a workspace holds at most 100."}),"\n",(0,r.jsxs)(d.p,{children:["Each row's ",(0,r.jsx)(d.code,{children:"source"})," is ",(0,r.jsx)(d.code,{children:"organisation"})," for a Data Set your workspace made, which it can change, or ",(0,r.jsx)(d.code,{children:"system"})," for a built-in one, which cannot be written to and also answers to its ",(0,r.jsx)(d.code,{children:"slug"}),". Rows carry ",(0,r.jsx)(d.code,{children:"fieldCount"})," and ",(0,r.jsx)(d.code,{children:"recordCount"})," but no fields; ",(0,r.jsx)(d.code,{children:"get_data_set"})," has those."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsx)(d.tbody,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"includeSystem"})}),(0,r.jsx)(d.td,{children:"boolean"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["Include the built-in Data Sets. Default ",(0,r.jsx)(d.code,{children:"true"}),". Send ",(0,r.jsx)(d.code,{children:"false"})," for only the ones your workspace made."]})]})})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsxs)(d.li,{children:["Returns: the standard list envelope (see ",(0,r.jsx)(d.a,{href:"/docs/api-v3/pagination",children:"Pagination"}),") holding ",(0,r.jsx)(d.a,{href:"/docs/api-v3/data-sets#the-data-set-object",children:"Data Set objects"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"readOnlyHint"})," true, ",(0,r.jsx)(d.code,{children:"idempotentHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"GET /v3/data-sets"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "What Data Sets do we have in CheckFlow?"'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"get_data_set",children:(0,r.jsx)(d.code,{children:"get_data_set"})}),"\n",(0,r.jsxs)(d.p,{children:["Returns one Data Set with its fields and its saved views \u2014 everything needed to read or write its records or link a template field to it. It does not include records; a Data Set holds up to 10,000 and ",(0,r.jsx)(d.code,{children:"list_data_set_records"})," pages through them. A view whose filter or sort reports no ",(0,r.jsx)(d.code,{children:"fieldName"})," points at a field that has been deleted: that clause has had no effect since, and the next write to the view drops it."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsx)(d.tbody,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The Data Set's key, or a built-in Data Set's slug such as ",(0,r.jsx)(d.code,{children:"system-countries"}),"."]})]})})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsxs)(d.li,{children:["Returns: a ",(0,r.jsx)(d.a,{href:"/docs/api-v3/data-sets#the-data-set-object",children:"Data Set object"})," with ",(0,r.jsx)(d.code,{children:"fields"})," and ",(0,r.jsx)(d.code,{children:"views"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"readOnlyHint"})," true, ",(0,r.jsx)(d.code,{children:"idempotentHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"GET /v3/data-sets/{dataSetKey}"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "What fields and views does the Suppliers Data Set have?"'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"create_data_set",children:(0,r.jsx)(d.code,{children:"create_data_set"})}),"\n",(0,r.jsxs)(d.p,{children:["Creates a Data Set. The description tells the model to name the fields in the same call if it knows them: a Data Set created with none is given a single text field called ",(0,r.jsx)(d.code,{children:"Name"}),", which stays behind when the real fields are added. A workspace holds at most 100 Data Sets and a Data Set at most 50 fields. If the records are already in a CSV file, ",(0,r.jsx)(d.code,{children:"create_data_set_from_csv"})," does the whole job in one call."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"name"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The Data Set's name. Unique within the workspace."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"description"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsx)(d.td,{children:"What it is for."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"fields"})}),(0,r.jsx)(d.td,{children:"array of objects"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["The fields to start with, each ",(0,r.jsx)(d.code,{children:"name"}),", ",(0,r.jsx)(d.code,{children:"type"})," and ",(0,r.jsx)(d.code,{children:"description"}),". ",(0,r.jsx)(d.code,{children:"type"})," is ",(0,r.jsx)(d.code,{children:"text"}),", ",(0,r.jsx)(d.code,{children:"number"}),", ",(0,r.jsx)(d.code,{children:"date"}),", ",(0,r.jsx)(d.code,{children:"email"}),", ",(0,r.jsx)(d.code,{children:"url"})," or ",(0,r.jsx)(d.code,{children:"boolean"}),", and ",(0,r.jsx)(d.code,{children:"text"})," when left out. Fields are added in the order given; there is no position, and nothing reorders them later."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"idempotencyKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["Retries this call safely. See ",(0,r.jsx)(d.a,{href:"#how-to-read-this-page",children:"How to Read This Page"}),"."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsx)(d.li,{children:"Returns: the new Data Set object with its fields and views."}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," false."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"POST /v3/data-sets"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Create a Data Set called Suppliers with fields Supplier, Country, Contact Email and Active."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"update_data_set",children:(0,r.jsx)(d.code,{children:"update_data_set"})}),"\n",(0,r.jsxs)(d.p,{children:["Renames or re-describes a Data Set. Only these two can change here \u2014 fields, records and views have their own tools. Sending neither is refused rather than answered with an unchanged Data Set. A built-in Data Set is refused with ",(0,r.jsx)(d.code,{children:"FORBIDDEN"}),"."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The Data Set, by key or slug."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"name"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsx)(d.td,{children:"The new name. Cannot be cleared; leave it out to keep the current name."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"description"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsx)(d.td,{children:"The new description. Send an empty string to clear it."})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsx)(d.li,{children:"Returns: the Data Set object with its fields and views."}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," false, ",(0,r.jsx)(d.code,{children:"idempotentHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"PATCH /v3/data-sets/{dataSetKey}"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Rename the Suppliers Data Set to Approved Suppliers."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"delete_data_set",children:(0,r.jsx)(d.code,{children:"delete_data_set"})}),"\n",(0,r.jsxs)(d.p,{children:["Deletes a Data Set. It is refused while any template field still reads from it, and the refusal names the templates, because a drop-down whose Data Set has gone offers nothing and says nothing about why. ",(0,r.jsx)(d.code,{children:"list_data_set_connections"})," lists the fields themselves. ",(0,r.jsx)(d.code,{children:"force"})," deletes the links too, clearing them from every version of every template \u2014 while the refusal only names the latest version of each, so a forced delete can touch templates the refusal did not mention."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The Data Set, by key or slug."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"force"})}),(0,r.jsx)(d.td,{children:"boolean"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["Delete it even though template fields read from it, breakin
1g their links. Default ",(0,r.jsx)(d.code,{children:"false"}),"."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsx)(d.li,{children:"Returns: nothing."}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," true, ",(0,r.jsx)(d.code,{children:"idempotentHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"DELETE /v3/data-sets/{dataSetKey}"})," (with ",(0,r.jsx)(d.code,{children:"?force=true"}),")."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Delete the old Suppliers Data Set if nothing uses it."'}),"\n"]}),"\n",(0,r.jsx)(d.admonition,{type:"danger",children:(0,r.jsxs)(d.p,{children:["A deleted Data Set, and its records, cannot be recovered. With ",(0,r.jsx)(d.code,{children:"force"}),", every template field that read from it loses its link."]})}),"\n",(0,r.jsx)(d.h2,{id:"list_data_set_connections",children:(0,r.jsx)(d.code,{children:"list_data_set_connections"})}),"\n",(0,r.jsxs)(d.p,{children:["Lists every template field linked to one of this Data Set's views, with the template, the version, the field's key and its label. It is what stands between a Data Set and deleting it, and a partial answer to \"what breaks if I remove this field\" \u2014 partial because it reports the view each template field uses, not which Data Set field it shows or how a Table field maps its columns. A connection with no ",(0,r.jsx)(d.code,{children:"viewName"})," is a template field pointing at a view that has been deleted; the template designer refuses to save until somebody repoints it. See ",(0,r.jsx)(d.a,{href:"/docs/data-sets/linking-to-controls",children:"Linking a Data Set to a Control"}),"."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsx)(d.tbody,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The Data Set, by key or slug."})]})})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsxs)(d.li,{children:["Returns: the standard list envelope holding ",(0,r.jsx)(d.a,{href:"/docs/api-v3/data-sets#the-connection-object",children:"Connection objects"}),", each with ",(0,r.jsx)(d.code,{children:"templateKey"}),", ",(0,r.jsx)(d.code,{children:"templateName"}),", ",(0,r.jsx)(d.code,{children:"templateVersion"}),", ",(0,r.jsx)(d.code,{children:"templateUrl"}),", ",(0,r.jsx)(d.code,{children:"controlKey"}),", ",(0,r.jsx)(d.code,{children:"controlLabel"}),", ",(0,r.jsx)(d.code,{children:"controlType"}),", ",(0,r.jsx)(d.code,{children:"viewKey"})," and ",(0,r.jsx)(d.code,{children:"viewName"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"readOnlyHint"})," true, ",(0,r.jsx)(d.code,{children:"idempotentHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"GET /v3/data-sets/{dataSetKey}/connections"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Which templates use the Suppliers Data Set?"'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"create_data_set_field",children:(0,r.jsx)(d.code,{children:"create_data_set_field"})}),"\n",(0,r.jsx)(d.p,{children:"Adds a field after the ones already there. There is no position argument, because nothing in CheckFlow renumbers fields. A Data Set holds at most 50 fields, and a name another field already has, ignoring case, is refused, because names are how record cells are addressed."}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The Data Set, by key or slug. A built-in one is refused with ",(0,r.jsx)(d.code,{children:"FORBIDDEN"}),"."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"name"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The field's name, at most 200 characters."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"type"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:[(0,r.jsx)(d.code,{children:"text"}),", ",(0,r.jsx)(d.code,{children:"number"}),", ",(0,r.jsx)(d.code,{children:"date"}),", ",(0,r.jsx)(d.code,{children:"email"}),", ",(0,r.jsx)(d.code,{children:"url"})," or ",(0,r.jsx)(d.code,{children:"boolean"}),". Default ",(0,r.jsx)(d.code,{children:"text"}),". Every value written into the field afterwards is checked against it; widening the type later is allowed, narrowing it is refused while any record holds a value the new type would not take."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"description"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsx)(d.td,{children:"What the field is for."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"idempotencyKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["Retries this call safely. See ",(0,r.jsx)(d.a,{href:"#how-to-read-this-page",children:"How to Read This Page"}),"."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsxs)(d.li,{children:["Returns: the new ",(0,r.jsx)(d.a,{href:"/docs/api-v3/data-sets#the-field-object",children:"Field object"}),", with ",(0,r.jsx)(d.code,{children:"key"}),", ",(0,r.jsx)(d.code,{children:"name"}),", ",(0,r.jsx)(d.code,{children:"type"}),", ",(0,r.jsx)(d.code,{children:"description"})," and ",(0,r.jsx)(d.code,{children:"position"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," false."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"POST /v3/data-sets/{dataSetKey}/fields"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Add a Payment Terms field to the Suppliers Data Set."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"update_data_set_field",children:(0,r.jsx)(d.code,{children:"update_data_set_field"})}),"\n",(0,r.jsxs)(d.p,{children:["Renames, retypes or re-describes a field. Send only what is changing; sending none of the three is refused. Retyping can fail on the data: every record is read first, and a text field holding ",(0,r.jsx)(d.code,{children:"n/a"}
1)," cannot become a number field while that record is there. The refusal names the type but not the record \u2014 ",(0,r.jsx)(d.code,{children:"list_data_set_records"})," is how to find it. Renaming is safe for the records, which are stored against the field's key, but a caller writing cells by name must use the new name afterwards."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The Data Set, by key or slug."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"fieldKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The field's key, from ",(0,r.jsx)(d.code,{children:"get_data_set"}),"."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"name"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsx)(d.td,{children:"The new name. Cannot be cleared."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"type"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["The new type: ",(0,r.jsx)(d.code,{children:"text"}),", ",(0,r.jsx)(d.code,{children:"number"}),", ",(0,r.jsx)(d.code,{children:"date"}),", ",(0,r.jsx)(d.code,{children:"email"}),", ",(0,r.jsx)(d.code,{children:"url"})," or ",(0,r.jsx)(d.code,{children:"boolean"}),". Cannot be cleared."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"description"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsx)(d.td,{children:"The new description. Send an empty string to clear it."})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsx)(d.li,{children:"Returns: the field as it now stands."}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," false, ",(0,r.jsx)(d.code,{children:"idempotentHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"PATCH /v3/data-sets/{dataSetKey}/fields/{fieldKey}"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Change the Credit Limit field in Suppliers to a number."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"delete_data_set_field",children:(0,r.jsx)(d.code,{children:"delete_data_set_field"})}),"\n",(0,r.jsxs)(d.p,{children:["Deletes a field and every value in it. The field's key is stripped out of every record before the field itself goes, so the data is gone and nothing keeps a copy. There is no ",(0,r.jsx)(d.code,{children:"force"}),". It is refused in two cases: a field a template reads from (a conflict), and the last remaining field (invalid, because a Data Set with no fields can hold nothing). The conflict cannot name the template field; ",(0,r.jsx)(d.code,{children:"list_data_set_connections"})," narrows it to this Data Set's connections."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The Data Set, by key or slug."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"fieldKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The field's key, from ",(0,r.jsx)(d.code,{children:"get_data_set"}),"."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsx)(d.li,{children:"Returns: nothing."}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," true, ",(0,r.jsx)(d.code,{children:"idempotentHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"DELETE /v3/data-sets/{dataSetKey}/fields/{fieldKey}"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Remove the Fax Number field from the Suppliers Data Set."'}),"\n"]}),"\n",(0,r.jsx)(d.admonition,{type:"danger",children:(0,r.jsx)(d.p,{children:"Deleting a field permanently removes its value from every record."})}),"\n",(0,r.jsx)(d.h2,{id:"list_data_set_records",children:(0,r.jsx)(d.code,{children:"list_data_set_records"})}),"\n",(0,r.jsxs)(d.p,{children:["Returns a page of records. Cells come back keyed by field name, with every field present and ",(0,r.jsx)(d.code,{children:"null"})," for an empty cell, so every record has the same keys. There are no sort or filter arguments: a Data Set orders and filters through a saved view, so ",(0,r.jsx)(d.code,{children:"view"})," is the sort, the filter and the column selection at once. A record's ",(0,r.jsx)(d.code,{children:"position"}
1)," is its place in the Data Set even when a view has reordered the page."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The Data Set, by key or slug."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"view"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["A view's key, from ",(0,r.jsx)(d.code,{children:"get_data_set"}),". Its filters, sorts and hidden fields apply. Omit for every record in the Data Set's own order. Cells the view hides are still returned."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"after"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["The ",(0,r.jsx)(d.code,{children:"nextCursor"})," from the previous page. Send the same ",(0,r.jsx)(d.code,{children:"view"})," and ",(0,r.jsx)(d.code,{children:"pageSize"})," with it; changing either mid-walk is refused."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"pageSize"})}),(0,r.jsx)(d.td,{children:"integer"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["Records per page, ",(0,r.jsx)(d.code,{children:"1"})," to ",(0,r.jsx)(d.code,{children:"100"}),". Default ",(0,r.jsx)(d.code,{children:"50"}),". A value outside the range is not refused; the default of ",(0,r.jsx)(d.code,{children:"50"})," is used instead."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsxs)(d.li,{children:["Returns: the standard list envelope holding ",(0,r.jsx)(d.a,{href:"/docs/api-v3/data-sets#the-record-object",children:"Record objects"}),", each with ",(0,r.jsx)(d.code,{children:"key"}),", ",(0,r.jsx)(d.code,{children:"position"})," and ",(0,r.jsx)(d.code,{children:"values"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"readOnlyHint"})," true, ",(0,r.jsx)(d.code,{children:"idempotentHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"GET /v3/data-sets/{dataSetKey}/records"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "List the active suppliers in the Suppliers Data Set."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"get_data_set_record",children:(0,r.jsx)(d.code,{children:"get_data_set_record"})}),"\n",(0,r.jsxs)(d.p,{children:["Returns one record by key. It is for a record whose key is already in hand \u2014 from a write or a webhook \u2014 rather than for finding one: there is no search over records, and a record is found by its contents by listing through a view that filters on them. A key belonging to another Data Set's record is refused with ",(0,r.jsx)(d.code,{children:"DATA_SET_RECORD_NOT_FOUND"}),"."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The Data Set, by key or slug."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"recordKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The record's key, from ",(0,r.jsx)(d.code,{children:"list_data_set_records"}),"."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsxs)(d.li,{children:["Returns: the record, with ",(0,r.jsx)(d.code,{children:"key"}),", ",(0,r.jsx)(d.code,{children:"position"})," and ",(0,r.jsx)(d.code,{children:"values"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"readOnlyHint"})," true, ",(0,r.jsx)(d.code,{children:"idempotentHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"GET /v3/data-sets/{dataSetKey}/records/{recordKey}"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Show me the Suppliers record from that webhook."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"create_data_set_record",children:(0,r.jsx)(d.code,{children:"create_data_set_record"})}),"\n",(0,r.jsxs)(d.p,{children:["Adds one record and fires the ",(0,r.jsx)(d.code,{children:"data_set.record.created"})," webhook for it. The description points the model to ",(0,r.jsx)(d.code,{children:"create_data_set_records"})," for more than one record, which fires no webhooks \u2014 so this is the tool to use when a subscriber must hear about each new record. Cells may be left out entirely; a blank record is allowed. A Data Set holds at most 10,000 records."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The Data Set, by key or slug. A built-in one is refused with ",(0,r.jsx)(d.code,{children:"FORBIDDEN"}),"."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"values"})}),(0,r.jsx)(d.td,{children:"object"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["The record's cells, keyed by field name or key, for example ",(0,r.jsx)(d.code,{children:'{"Supplier": "Northwind Ltd", "Credit Limit": 5000, "Active": true}'}),". Values are strings, numbers or booleans and are stored as text; a list or an object is refused. ",(0,r.jsx)(d.code,{children:"null"})," and the empty string are both an empty cell. Every value is checked against its field's type."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"idempotencyKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["Retries this call safely. See ",(0,r.jsx)(d.a,{href:"#how-to-read-this-page",children:"How to Read This Page"}),"."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsx)(d.li,{children:"Returns: the new record."}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," false."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"POST /v3/data-sets/{dataSetKey}/records"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Add Northwind Ltd, United Kingdom, to the Suppliers Data Set."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"update_data_set_record",children:(0,r.jsx)(d.code,{children:"update_data_set_record"})}),"\n",(0,r.jsxs)(d.p,{children:["Changes cells of one record. It merges rather than replaces: name only the cells that change and the rest are kept. Send a cell as ",(0,r.jsx)(d.code,{children:"null"})," to empty it. An empty ",(0,r.jsx)(d.code,{children:"values"})," is refused. The answer is read back from storage, so a boolean written as ",(0,r.jsx)(d.code,{children:"yes"})," comes back as ",(0,r.jsx)(d.code,{children:"true"})," \u2014 the model is told to read it rather than assume."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The Data Set, by key or slug."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"recordKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The record's key, from ",(0,r.jsx)(d.code,{children:"list_data_set_records"}),"."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"values"})}),(0,r.jsx)(d.td,{children:"object"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The cells to change, keyed by field name or key. A cell left out is left alone; a cell sent as ",(0,r.jsx)(d.code,{children:"null"})," is emptied. The same value rules as ",(0,r.jsx)(d.code,{children:"create_data_set_record"}),"."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsx)(d.li,{children:"Returns: the record as stored."}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," false, ",(0,r.jsx)(d.code,{children:"idempotentHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"PATCH /v3/data-sets/{dataSetKey}/records/{recordKey}"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Mark Northwind Ltd as inactive in Suppliers."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"create_data_set_records",children:(0,r.jsx)(d.code,{children:"create_data_set_records"})}),"\n",(0,r.jsxs)(d.p,{children:["Writes up to 1,000 records in one call, appending them or replacing the whole Data Set. It is all or nothing: every record is checked against the fields before any is written, so one bad cell refuses the call and says where \u2014 for example ",(0,r.jsx)(d.code,{children:"records[41].values.Supplier"}),". No webhooks fire for the records it writes, nor for the records a replace removes; a 10,000-record replace would otherwise send 20,000 events. A replace runs in one transaction, so a failure part-way leaves the Data Set as it was. The 10,000-record limit applies to the total, not to the call."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The Data Set, by key or slug. A built-in one is refused with ",(0,r.jsx)(d.code,{children:"FORBIDDEN"}),"."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"records"})}),(0,r.jsx)(d.td,{children:"array of objects"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The records, each ",(0,r.jsx)(d.code,{children:'{ "values": { \u2026 } }'})," with cells keyed as ",(0,r.jsx)(d.code,{children:"create_data_set_record"})," takes them. A record with no values is a blank record. At most 1,000."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"mode"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:[(0,r.jsx)(d.code,{children:"append"})," to add after the existing records, or ",(0,r.jsx)(d.code,{children:"replace"})," to make these the whole contents. Default ",(0,r.jsx)(d.code,{children:"append"}),". Anything else is refused."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"idempotencyKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["Retries this call safely. See ",(0,r.jsx)(d.a,{href:"#how-to-read-this-page",children:"How to Read This Page"}),"."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsxs)(d.li,{children:["Returns: an object with ",(0,r.jsx)(d.code,{children:"mode"}),", ",(0,r.jsx)(d.code,{children:"created"}),", ",(0,r.jsx)(d.code,{children:"recordCount"})," and ",(0,r.jsx)(d.code,{children:"records"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"POST /v3/data-sets/{dataSetKey}/records/bulk"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Replace everything in the Suppliers Data Set with these 40 suppliers."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"delete_data_set_records",children:(0,r.jsx)(d.code,{children:"delete_data_set_records"})}),"\n",(0,r.jsxs)(d.p,{children:["Deletes records by key \u2014 one, or up to 1,000. There is no separate single-record tool. It is all or nothing: every key is checked against this Data Set's records first, and a key matching none of them refuses the whole call, so a partial delete cannot pass for a complete one. A key sent twice is deleted once. One ",(0,r.jsx)(d.code,{children:"data_set.record.deleted"})," webhook fires per key."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The Data Set, by key or slug. A built-in one is refused with ",(0,r.jsx)(d.code,{children:"FORBIDDEN"}),"."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"recordKeys"})}
1),(0,r.jsx)(d.td,{children:"array of strings"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The records to delete, from ",(0,r.jsx)(d.code,{children:"list_data_set_records"}),". At least one, at most 1,000."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsx)(d.li,{children:"Returns: nothing."}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," true, ",(0,r.jsx)(d.code,{children:"idempotentHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"DELETE /v3/data-sets/{dataSetKey}/records/bulk"})," (and ",(0,r.jsx)(d.code,{children:"DELETE /v3/data-sets/{dataSetKey}/records/{recordKey}"})," for one)."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Delete the three inactive suppliers from the Suppliers Data Set."'}),"\n"]}),"\n",(0,r.jsx)(d.admonition,{type:"danger",children:(0,r.jsx)(d.p,{children:"Deleted records cannot be recovered."})}),"\n",(0,r.jsx)(d.h2,{id:"create_data_set_view",children:(0,r.jsx)(d.code,{children:"create_data_set_view"})}),"\n",(0,r.jsxs)(d.p,{children:["Saves a way of looking at the records: which of them, in what order, with which fields hidden. A template field links to a view, so a drop-down that offers only active suppliers is a view with a filter on it. A Data Set holds at most 20 views. A view with no filters, sorts or hidden fields shows every record in the Data Set's own order \u2014 which is what the ",(0,r.jsx)(d.code,{children:"All Records"})," view every Data Set starts with already does."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The Data Set, by key or slug."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"name"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The view's name."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"filters"})}),(0,r.jsx)(d.td,{children:"array of objects"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["Which records, each ",(0,r.jsx)(d.code,{children:"field"}),", ",(0,r.jsx)(d.code,{children:"operator"})," and ",(0,r.jsx)(d.code,{children:"value"}),". ",(0,r.jsx)(d.code,{children:"field"})," is a field's name or key. ",(0,r.jsx)(d.code,{children:"operator"})," is ",(0,r.jsx)(d.code,{children:"eq"}),", ",(0,r.jsx)(d.code,{children:"neq"}),", ",(0,r.jsx)(d.code,{children:"contains"}),", ",(0,r.jsx)(d.code,{children:"not_contains"}),", ",(0,r.jsx)(d.code,{children:"starts_with"}),", ",(0,r.jsx)(d.code,{children:"ends_with"}),", ",(0,r.jsx)(d.code,{children:"gt"}),", ",(0,r.jsx)(d.code,{children:"gte"}),", ",(0,r.jsx)(d.code,{children:"lt"}),", ",(0,r.jsx)(d.code,{children:"lte"}),", ",(0,r.jsx)(d.code,{children:"is_empty"}),", ",(0,r.jsx)(d.code,{children:"is_not_empty"})," or ",(0,r.jsx)(d.code,{children:"in"}),"; anything else is refused. ",(0,r.jsx)(d.code,{children:"value"})," is required except for ",(0,r.jsx)(d.code,{children:"is_empty"})," and ",(0,r.jsx)(d.code,{children:"is_not_empty"}),", which refuse one; for ",(0,r.jsx)(d.code,{children:"in"})," it is a comma-separated list. Filters are combined with AND."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"sorts"})}),(0,r.jsx)(d.td,{children:"array of objects"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["The order, each ",(0,r.jsx)(d.code,{children:"field"})," and ",(0,r.jsx)(d.code,{children:"direction"})," (",(0,r.jsx)(d.code,{children:"asc"})," or ",(0,r.jsx)(d.code,{children:"desc"}),", default ",(0,r.jsx)(d.code,{children:"asc"}),"), applied in array order. Any other direction is refused."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"hiddenFields"})}
1),(0,r.jsx)(d.td,{children:"array of strings"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsx)(d.td,{children:"Fields the view leaves out, by name or key. Hiding every field is refused."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"idempotencyKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["Retries this call safely. See ",(0,r.jsx)(d.a,{href:"#how-to-read-this-page",children:"How to Read This Page"}),"."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsxs)(d.li,{children:["Returns: the new ",(0,r.jsx)(d.a,{href:"/docs/api-v3/data-sets#the-view-object",children:"View object"}),", with ",(0,r.jsx)(d.code,{children:"key"}),", ",(0,r.jsx)(d.code,{children:"name"}),", ",(0,r.jsx)(d.code,{children:"isDefault"}),", ",(0,r.jsx)(d.code,{children:"filters"}),", ",(0,r.jsx)(d.code,{children:"sorts"}),", ",(0,r.jsx)(d.code,{children:"hiddenFieldKeys"})," and ",(0,r.jsx)(d.code,{children:"hiddenFieldNames"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," false."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"POST /v3/data-sets/{dataSetKey}/views"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Create a view of Suppliers called Active UK Suppliers that shows only active suppliers in the United Kingdom, sorted by name."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"update_data_set_view",children:(0,r.jsx)(d.code,{children:"update_data_set_view"})}),"\n",(0,r.jsx)(d.p,{children:"Changes a view. Send only what changes: a list left out is kept as it is. A list that is sent replaces the old one whole rather than merging clause by clause, and an empty array clears it. A Data Set's default view can be refiltered but not renamed, and which view is the default cannot be changed."}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The Data Set, by key or slug."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"viewKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The view's key, from ",(0,r.jsx)(d.code,{children:"get_data_set"}),"."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"name"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsx)(d.td,{children:"The new name. Cannot be cleared, and cannot be set on the default view."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"filters"})}),(0,r.jsx)(d.td,{children:"array of objects"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["The view's filters, replacing all of them. Same shape and rules as ",(0,r.jsx)(d.code,{children:"create_data_set_view"}),". ",(0,r.jsx)(d.code,{children:"[]"})," clears them."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"sorts"})}),(0,r.jsx)(d.td,{children:"array of objects"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["The view's sorts, replacing all of them. ",(0,r.jsx)(d.code,{children:"[]"})," clears them."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"hiddenFields"})}),(0,r.jsx)(d.td,{children:"array of strings"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["The fields the view hides, replacing all of them. ",(0,r.jsx)(d.code,{children:"[]"})," shows every field again."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsx)(d.li,{children:"Returns: the view as it now stands."}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," false, ",(0,r.jsx)(d.code,{children:"idempotentHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"PATCH /v3/data-sets/{dataSetKey}/views/{viewKey}"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Remove the country filter from the Active UK Suppliers view."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"delete_data_set_view",children:(0,r.jsx)(d.code,{children:"delete_data_set_view"})}),"\n",(0,r.jsxs)(d.p,{children:["Deletes a view. Unlike deleting a Data Set, deleting a view a template field reads from is allowed: the template field is left pointing at nothing, which the template designer reports and refuses to save over until somebody repoints it. The description tells the model to read ",(0,r.jsx)(d.code,{children:"list_data_set_connections"})," first. A Data Set's default view cannot be deleted."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The Data Set, by key or slug."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"viewKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The view's key, from ",(0,r.jsx)(d.code,{children:"get_data_set"}),"."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsx)(d.li,{children:"Returns: nothing."}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," true, ",(0,r.jsx)(d.code,{children:"idempotentHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"DELETE /v3/data-sets/{dataSetKey}/views/{viewKey}"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Delete the Active UK Suppliers view."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"create_data_set_from_csv",children:(0,r.jsx)(d.code,{children:"create_data_set_from_csv"})}),"\n",(0,r.jsxs)(d.p,{children:["Makes a Data Set from CSV text: the header line becomes the fields, every other line a record, and each field's type is guessed from its values. The types cannot be set here; a field guessed too narrowly can be widened afterwards with ",(0,r.jsx)(d.code,{children:"update_data_set_field"}),". The answer lists the fields created, in the file's order. See ",(0,r.jsx)(d.a,{href:"/docs/data-sets/import-export",children:"Importing and Exporting CSV"}),"."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"name"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The Data Set's name."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"csv"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The file's text. The first line names the fields. Quoting follows RFC 4180: a value holding a comma, a quote or a line break is wrapped in double quotes, and its own quotes are doubled. A leading byte-order mark is ignored."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"description"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsx)(d.td,{children:"What the Data Set is for."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"idempotencyKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["Retries this call safely. See ",(0,r.jsx)(d.a,{href:"#how-to-read-this-page",children:"How to Read This Page"}),"."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsxs)(d.li,{children:["Returns: an object with ",(0,r.jsx)(d.code,{children:"dataSet"})," (the new Data Set with its fields and views), ",(0,r.jsx)(d.code,{children:"recordsImported"})," and ",(0,r.jsx)(d.code,{children:"fieldsAdded"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," false."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"POST /v3/data-sets/import"}),"."]}
1),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Turn this spreadsheet of suppliers into a CheckFlow Data Set called Suppliers."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"replace_data_set_records_from_csv",children:(0,r.jsx)(d.code,{children:"replace_data_set_records_from_csv"})}),"\n",(0,r.jsxs)(d.p,{children:["Replaces every record of an existing Data Set from CSV text. It replaces rather than appends \u2014 ",(0,r.jsx)(d.code,{children:"create_data_set_records"})," with ",(0,r.jsx)(d.code,{children:"mode"})," ",(0,r.jsx)(d.code,{children:"append"})," is the append. Columns are matched to fields by name, ignoring case. A column with no matching field creates one, and a field no column names is kept and left empty in every record. That first rule is why the answer reports ",(0,r.jsx)(d.code,{children:"fieldsAdded"}),": a misspelled header adds a field, and the answer is the only place that says so."]}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The Data Set, by key or slug. A built-in one is refused with ",(0,r.jsx)(d.code,{children:"FORBIDDEN"}),"."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"csv"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsxs)(d.td,{children:["The file's text, as ",(0,r.jsx)(d.code,{children:"create_data_set_from_csv"})," describes it."]})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"idempotencyKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsxs)(d.td,{children:["Retries this call safely. See ",(0,r.jsx)(d.a,{href:"#how-to-read-this-page",children:"How to Read This Page"}),"."]})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsxs)(d.li,{children:["Returns: an object with ",(0,r.jsx)(d.code,{children:"dataSet"}),", ",(0,r.jsx)(d.code,{children:"recordsImported"})," and ",(0,r.jsx)(d.code,{children:"fieldsAdded"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"destructiveHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"POST /v3/data-sets/{dataSetKey}/import"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Replace the Suppliers records with the contents of this CSV."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"export_data_set_csv",children:(0,r.jsx)(d.code,{children:"export_data_set_csv"})}),"\n",(0,r.jsx)(d.p,{children:"Returns a Data Set's records as CSV text in the answer, with the file name the app would have used. Anything this exports can be imported again: an export larger than an import would accept (5 MB) is refused rather than truncated. Built-in Data Sets export like any other."}),"\n",(0,r.jsxs)(d.table,{children:[(0,r.jsx)(d.thead,{children:(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.th,{children:"Name"}),(0,r.jsx)(d.th,{children:"Type"}),(0,r.jsx)(d.th,{children:"Required"}),(0,r.jsx)(d.th,{children:"Description"})]})}),(0,r.jsxs)(d.tbody,{children:[(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"dataSetKey"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"Yes"}),(0,r.jsx)(d.td,{children:"The Data Set, by key or slug."})]}),(0,r.jsxs)(d.tr,{children:[(0,r.jsx)(d.td,{children:(0,r.jsx)(d.code,{children:"view"})}),(0,r.jsx)(d.td,{children:"string"}),(0,r.jsx)(d.td,{children:"No"}),(0,r.jsx)(d.td,{children:"A view's key. Its filters, sorts and hidden fields apply, and a hidden field is left out of the file. Omit for the Data Set's default view. A view that hides every field is refused."})]})]})]}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsxs)(d.li,{children:["Returns: an object with ",(0,r.jsx)(d.code,{children:"fileName"}),", ",(0,r.jsx)(d.code,{children:"contentType"}),", ",(0,r.jsx)(d.code,{children:"viewKey"}),", ",(0,r.jsx)(d.code,{children:"viewName"}),", ",(0,r.jsx)(d.code,{children:"columns"}),", ",(0,r.jsx)(d.code,{children:"rowCount"})," and ",(0,r.jsx)(d.code,{children:"csv"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:["Annotations: ",(0,r.jsx)(d.code,{children:"readOnlyHint"})," true, ",(0,r.jsx)(d.code,{children:"idempotentHint"})," true."]}),"\n",(0,r.jsxs)(d.li,{children:["REST equivalent: ",(0,r.jsx)(d.code,{children:"GET /v3/data-sets/{dataSetKey}/export"}),"."]}),"\n",(0,r.jsx)(d.li,{children:'Example prompt: "Export the Suppliers Data Set as CSV."'}),"\n"]}),"\n",(0,r.jsx)(d.h2,{id:"related-pages",children:"Related Pages"}),"\n",(0,r.jsxs)(d.ul,{children:["\n",(0,r.jsxs)(d.li,{children:[(0,r.jsx)(d.a,{href:"/docs/api-v3/data-sets",children:"Data Sets"})," \u2014 the REST routes behind these tools, with the full Data Set, field, record and view objects."]}),"\n",(0,r.jsxs)(d.li,{children:[(0,r.jsx)(d.a,{href:"/docs/data-sets/views",children:"Views"})," \u2014 how saved views filter and sort records in the app."]}),"\n",(0,r.jsxs)(d.li,{children:[(0,r.jsx)(d.a,{href:"/docs/data-sets/linking-to-controls",children:"Linking a Data Set to a Control"})," \u2014 what a template field linked to a view offers the people running a checklist."]}),"\n",(0,r.jsxs)(d.li,{children:[(0,r.jsx)(d.a,{href:"/docs/mcp/tools-templates",children:"Template Authoring Tools"})," \u2014 how a template document links a field to a Data Set with ",(0,r.jsx)(d.code,{children:"dataSet"}),"."]}),"\n",(0,r.jsxs)(d.li,{children:[(0,r.jsx)(d.a,{href:"/docs/mcp/tools-webhooks",children:"Webhook Tools"})," \u2014 subscribing to the ",(0,r.jsx)(d.code,{children:"data_set.record.*"})," events these tools fire."]}),"\n"]})]})}function o(e={}){const{wrapper:d}={...(0,i.R)(),...e.components};return d?(0,r.jsx)(d,{...e,children:(0,r.jsx)(h,{...e})}):h(e)}},8453(e,d,t){t.d(d,{R:()=>n,x:()=>l});var s=t(6540);const r={},i=s.createContext(r);function n(e){const d=s.useContext(i);return s.useMemo(function(){return"function"==typeof e?e(d):{...d,...e}},[d,e])}function l(e){let d;return d=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:n(e.components),s.createElement(i.Provider,{value:d},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.