[{"data":1,"prerenderedAt":1880},["ShallowReactive",2],{"navigation_docs_en":3,"-en-reference-extensions-data-connectors-limitations":445,"-en-reference-extensions-data-connectors-limitations-surround":1875},[4,30,72,132,260,436],{"title":5,"icon":6,"path":7,"stem":8,"children":9,"page":6},"Getting Started",false,"\u002Fen\u002Fgetting-started","en\u002F1.getting-started",[10,15,20,25],{"title":11,"path":12,"stem":13,"icon":14},"Introduction","\u002Fen\u002Fgetting-started\u002Fintroduction","en\u002F1.getting-started\u002F2.introduction","i-lucide-house",{"title":16,"path":17,"stem":18,"icon":19},"Quickstart","\u002Fen\u002Fgetting-started\u002Finstallation","en\u002F1.getting-started\u002F3.installation","i-lucide-download",{"title":21,"path":22,"stem":23,"icon":24},"Use Cases","\u002Fen\u002Fgetting-started\u002Fuse-cases","en\u002F1.getting-started\u002F4.use-cases","i-lucide-layers",{"title":26,"path":27,"stem":28,"icon":29},"Concepts","\u002Fen\u002Fgetting-started\u002Fconcepts","en\u002F1.getting-started\u002F5.concepts","i-lucide-book",{"title":26,"path":31,"stem":32,"children":33,"page":6},"\u002Fen\u002Fconcepts","en\u002F2.concepts",[34,38,43,48,53,58,63,68],{"title":35,"path":36,"stem":37,"icon":14},"Organization","\u002Fen\u002Fconcepts\u002Forganization","en\u002F2.concepts\u002F1.organization",{"title":39,"path":40,"stem":41,"icon":42},"Data Model","\u002Fen\u002Fconcepts\u002Fdata-model","en\u002F2.concepts\u002F2.data-model","i-lucide-database",{"title":44,"path":45,"stem":46,"icon":47},"Access Control","\u002Fen\u002Fconcepts\u002Faccess-permissions","en\u002F2.concepts\u002F3.access-permissions","i-lucide-user-key",{"title":49,"path":50,"stem":51,"icon":52},"Audit Logs","\u002Fen\u002Fconcepts\u002Faudit-logs","en\u002F2.concepts\u002F4.audit-logs","i-lucide-scroll-text",{"title":54,"path":55,"stem":56,"icon":57},"Introspection","\u002Fen\u002Fconcepts\u002Fintrospection","en\u002F2.concepts\u002F6.introspection","i-lucide-database-search",{"title":59,"path":60,"stem":61,"icon":62},"Query Engine","\u002Fen\u002Fconcepts\u002Fquery-engine","en\u002F2.concepts\u002F7.query-engine","i-lucide-workflow",{"title":64,"path":65,"stem":66,"icon":67},"AI","\u002Fen\u002Fconcepts\u002Fai","en\u002F2.concepts\u002F8.ai","i-lucide-sparkles",{"title":69,"path":70,"stem":71,"icon":42},"Caching","\u002Fen\u002Fconcepts\u002Fcaching","en\u002F2.concepts\u002F9.caching",{"title":73,"path":74,"stem":75,"children":76,"page":6},"Guides","\u002Fen\u002Fguides","en\u002F4.guides",[77,82,87,92,97,102,107,112],{"title":78,"path":79,"stem":80,"icon":81},"REST API Quickstart","\u002Fen\u002Fguides\u002Frest-api","en\u002F4.guides\u002F1.rest-api","i-lucide-plug",{"title":83,"path":84,"stem":85,"icon":86},"SDK Quickstart","\u002Fen\u002Fguides\u002Fsdk","en\u002F4.guides\u002F2.sdk","i-lucide-terminal",{"title":88,"path":89,"stem":90,"icon":91},"Configure SSO","\u002Fen\u002Fguides\u002Fconfigure-sso","en\u002F4.guides\u002F3.configure-sso","i-lucide-key-round",{"title":93,"path":94,"stem":95,"icon":96},"Configure MCP","\u002Fen\u002Fguides\u002Fmcp","en\u002F4.guides\u002F4.mcp","i-lucide-brain-cog",{"title":98,"path":99,"stem":100,"icon":101},"Customize Content Space","\u002Fen\u002Fguides\u002Fcustomize-content-space","en\u002F4.guides\u002F5.customize-content-space","i-lucide-columns-3-cog",{"title":103,"path":104,"stem":105,"icon":106},"Build an Application with AI Assistance","\u002Fen\u002Fguides\u002Fbuild-an-application","en\u002F4.guides\u002F6.build-an-application","i-lucide-route",{"title":108,"path":109,"stem":110,"icon":111},"Horizontal Scaling","\u002Fen\u002Fguides\u002Fhorizontal-scaling","en\u002F4.guides\u002F7.horizontal-scaling","i-lucide-network",{"title":113,"icon":114,"path":115,"stem":116,"children":117,"page":6},"Data Connectors","i-lucide-cable","\u002Fen\u002Fguides\u002Fdata-connectors","en\u002F4.guides\u002F8.data-connectors",[118,122,127],{"title":16,"path":119,"stem":120,"icon":121},"\u002Fen\u002Fguides\u002Fdata-connectors\u002Fquickstart","en\u002F4.guides\u002F8.data-connectors\u002F1.quickstart","i-lucide-rocket",{"title":123,"path":124,"stem":125,"icon":126},"Build a Stripe Connector","\u002Fen\u002Fguides\u002Fdata-connectors\u002Fstripe","en\u002F4.guides\u002F8.data-connectors\u002F2.stripe","i-lucide-hammer",{"title":128,"path":129,"stem":130,"icon":131},"Build with AI Agents","\u002Fen\u002Fguides\u002Fdata-connectors\u002Fai-agents","en\u002F4.guides\u002F8.data-connectors\u002F3.ai-agents","i-lucide-bot",{"title":133,"path":134,"stem":135,"children":136,"page":6},"Developer","\u002Fen\u002Fdeveloper","en\u002F5.developer",[137,191,215,220],{"title":138,"path":139,"stem":140,"children":141,"page":6},"Data Access","\u002Fen\u002Fdeveloper\u002Fapi","en\u002F5.developer\u002F1.api",[142,147,152,157,162,167,172,177,182,186],{"title":143,"path":144,"stem":145,"icon":146},"Overview","\u002Fen\u002Fdeveloper\u002Fapi\u002Foverview","en\u002F5.developer\u002F1.api\u002F1.overview","i-lucide-globe",{"title":148,"path":149,"stem":150,"icon":151},"Errors","\u002Fen\u002Fdeveloper\u002Fapi\u002Ferrors","en\u002F5.developer\u002F1.api\u002F10.errors","i-lucide-alert-triangle",{"title":153,"path":154,"stem":155,"icon":156},"Authentication","\u002Fen\u002Fdeveloper\u002Fapi\u002Fauthentication","en\u002F5.developer\u002F1.api\u002F2.authentication","i-lucide-lock",{"title":158,"path":159,"stem":160,"icon":161},"Reading Data","\u002Fen\u002Fdeveloper\u002Fapi\u002Freading-data","en\u002F5.developer\u002F1.api\u002F3.reading-data","i-lucide-book-open",{"title":163,"path":164,"stem":165,"icon":166},"Writing Data","\u002Fen\u002Fdeveloper\u002Fapi\u002Fwriting-data","en\u002F5.developer\u002F1.api\u002F4.writing-data","i-lucide-pencil",{"title":168,"path":169,"stem":170,"icon":171},"Filtering","\u002Fen\u002Fdeveloper\u002Fapi\u002Ffiltering","en\u002F5.developer\u002F1.api\u002F5.filtering","i-lucide-filter",{"title":173,"path":174,"stem":175,"icon":176},"Field Selection","\u002Fen\u002Fdeveloper\u002Fapi\u002Ffield-selection","en\u002F5.developer\u002F1.api\u002F6.field-selection","i-lucide-list-checks",{"title":178,"path":179,"stem":180,"icon":181},"Sorting & Pagination","\u002Fen\u002Fdeveloper\u002Fapi\u002Fsorting-pagination","en\u002F5.developer\u002F1.api\u002F7.sorting-pagination","i-lucide-arrow-up-down",{"title":183,"path":184,"stem":185,"icon":111},"Relational Data","\u002Fen\u002Fdeveloper\u002Fapi\u002Frelational-data","en\u002F5.developer\u002F1.api\u002F8.relational-data",{"title":187,"path":188,"stem":189,"icon":190},"Files & Assets","\u002Fen\u002Fdeveloper\u002Fapi\u002Ffiles","en\u002F5.developer\u002F1.api\u002F9.files","i-lucide-file-up",{"title":192,"path":193,"stem":194,"children":195,"page":6},"Client SDK","\u002Fen\u002Fdeveloper\u002Fsdk","en\u002F5.developer\u002F2.sdk",[196,200,205,210],{"title":197,"path":198,"stem":199,"icon":19},"Installation","\u002Fen\u002Fdeveloper\u002Fsdk\u002Finstallation","en\u002F5.developer\u002F2.sdk\u002F1.installation",{"title":201,"path":202,"stem":203,"icon":204},"Client Setup","\u002Fen\u002Fdeveloper\u002Fsdk\u002Fclient-setup","en\u002F5.developer\u002F2.sdk\u002F2.client-setup","i-lucide-settings",{"title":206,"path":207,"stem":208,"icon":209},"Type System","\u002Fen\u002Fdeveloper\u002Fsdk\u002Ftype-system","en\u002F5.developer\u002F2.sdk\u002F3.type-system","i-lucide-braces",{"title":211,"path":212,"stem":213,"icon":214},"Advanced","\u002Fen\u002Fdeveloper\u002Fsdk\u002Fadvanced","en\u002F5.developer\u002F2.sdk\u002F5.advanced","i-lucide-puzzle",{"title":216,"path":217,"stem":218,"icon":219},"Application Users","\u002Fen\u002Fdeveloper\u002Fapplication-users","en\u002F5.developer\u002F3.application-users","i-lucide-users",{"title":221,"path":222,"stem":223,"children":224,"icon":214},"Extensions","\u002Fen\u002Fdeveloper\u002Fextensions","en\u002F5.developer\u002F3.extensions\u002Findex",[225,226,231],{"title":143,"path":222,"stem":223,"icon":214},{"title":227,"path":228,"stem":229,"icon":230},"Install and Manage Extensions","\u002Fen\u002Fdeveloper\u002Fextensions\u002Finstall","en\u002F5.developer\u002F3.extensions\u002F1.install","i-lucide-package-plus",{"title":113,"path":232,"stem":233,"children":234,"icon":114},"\u002Fen\u002Fdeveloper\u002Fextensions\u002Fdata-connectors","en\u002F5.developer\u002F3.extensions\u002F2.data-connectors\u002Findex",[235,236,241,245,250,255],{"title":143,"path":232,"stem":233,"icon":114},{"title":237,"path":238,"stem":239,"icon":240},"How Data Connectors Run","\u002Fen\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Fruntime","en\u002F5.developer\u002F3.extensions\u002F2.data-connectors\u002F2.runtime","i-lucide-cpu",{"title":242,"path":243,"stem":244,"icon":42},"Data Sources","\u002Fen\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Fdata-sources","en\u002F5.developer\u002F3.extensions\u002F2.data-connectors\u002F3.data-sources",{"title":246,"path":247,"stem":248,"icon":249},"Map an External Data Source","\u002Fen\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Fdata-source-mapping","en\u002F5.developer\u002F3.extensions\u002F2.data-connectors\u002F4.data-source-mapping","i-lucide-map",{"title":251,"path":252,"stem":253,"icon":254},"Handle Errors","\u002Fen\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Ferrors","en\u002F5.developer\u002F3.extensions\u002F2.data-connectors\u002F5.errors","i-lucide-shield-alert",{"title":256,"path":257,"stem":258,"icon":259},"Test a Data Connector","\u002Fen\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Ftesting","en\u002F5.developer\u002F3.extensions\u002F2.data-connectors\u002F6.testing","i-lucide-flask-conical",{"title":261,"path":262,"stem":263,"children":264,"page":6},"Reference","\u002Fen\u002Freference","en\u002F6.reference",[265,269,274,279,295,299,304,340,369,374],{"title":266,"path":267,"stem":268,"icon":204},"Configuration","\u002Fen\u002Freference\u002Fenvironment-variables","en\u002F6.reference\u002F1.environment-variables",{"title":270,"path":271,"stem":272,"icon":273},"System Requirements","\u002Fen\u002Freference\u002Fsystem-requirements","en\u002F6.reference\u002F2.system-requirements","i-lucide-server",{"title":275,"path":276,"stem":277,"icon":278},"Licensing","\u002Fen\u002Freference\u002Flicensing","en\u002F6.reference\u002F3.licensing","i-lucide-gem",{"title":280,"path":281,"stem":282,"children":283,"icon":81},"Connectors","\u002Fen\u002Freference\u002Fconnectors","en\u002F6.reference\u002F4.connectors\u002Findex",[284,285,290],{"title":280,"path":281,"stem":282,"icon":81},{"title":286,"path":287,"stem":288,"icon":289},"PostgreSQL and Supabase","\u002Fen\u002Freference\u002Fconnectors\u002Fpostgresql-supabase","en\u002F6.reference\u002F4.connectors\u002F1.postgresql-supabase","i-simple-icons-postgresql",{"title":291,"path":292,"stem":293,"icon":294},"MySQL and MariaDB","\u002Fen\u002Freference\u002Fconnectors\u002Fmysql-mariadb","en\u002F6.reference\u002F4.connectors\u002F2.mysql-mariadb","i-simple-icons-mysql",{"title":296,"path":297,"stem":298,"icon":209},"Data Types Representation","\u002Fen\u002Freference\u002Fdata-types","en\u002F6.reference\u002F5.data-types",{"title":300,"path":301,"stem":302,"icon":303},"Permissions Reference","\u002Fen\u002Freference\u002Fpermissions","en\u002F6.reference\u002F6.permissions","i-lucide-shield",{"title":305,"path":306,"stem":307,"children":308,"page":6},"API Reference","\u002Fen\u002Freference\u002Fapi-reference","en\u002F6.reference\u002F7.api-reference",[309,313,318],{"title":310,"path":311,"stem":312,"icon":273},"System Endpoints","\u002Fen\u002Freference\u002Fapi-reference\u002Fsystem-endpoints","en\u002F6.reference\u002F7.api-reference\u002F1.system-endpoints",{"title":314,"path":315,"stem":316,"icon":317},"OpenAPI Spec","\u002Fen\u002Freference\u002Fapi-reference\u002Fopenapi-spec","en\u002F6.reference\u002F7.api-reference\u002F2.openapi-spec","i-lucide-file-code",{"title":319,"path":320,"stem":321,"children":322,"icon":324},"Schema Migration","\u002Fen\u002Freference\u002Fapi-reference\u002Fschema-migration","en\u002F6.reference\u002F7.api-reference\u002F3.schema-migration\u002Findex",[323,325,330,335],{"title":319,"path":320,"stem":321,"icon":324},"i-lucide-database-zap",{"title":326,"path":327,"stem":328,"icon":329},"Apply Migrations","\u002Fen\u002Freference\u002Fapi-reference\u002Fschema-migration\u002Fapply-migrations","en\u002F6.reference\u002F7.api-reference\u002F3.schema-migration\u002F1.apply-migrations","i-lucide-upload",{"title":331,"path":332,"stem":333,"icon":334},"Import Changes","\u002Fen\u002Freference\u002Fapi-reference\u002Fschema-migration\u002Fimport-changes","en\u002F6.reference\u002F7.api-reference\u002F3.schema-migration\u002F2.import-changes","i-lucide-refresh-cw",{"title":336,"path":337,"stem":338,"icon":339},"Operation Reference","\u002Fen\u002Freference\u002Fapi-reference\u002Fschema-migration\u002Foperation-reference","en\u002F6.reference\u002F7.api-reference\u002F3.schema-migration\u002F3.operation-reference","i-lucide-list-tree",{"title":341,"path":342,"stem":343,"children":344,"page":6},"Design Considerations","\u002Fen\u002Freference\u002Fdesign-considerations","en\u002F6.reference\u002F8.design-considerations",[345,349,354,359,364],{"title":143,"path":346,"stem":347,"icon":348},"\u002Fen\u002Freference\u002Fdesign-considerations\u002Foverview","en\u002F6.reference\u002F8.design-considerations\u002F1.overview","i-lucide-compass",{"title":350,"path":351,"stem":352,"icon":353},"Instance Configuration","\u002Fen\u002Freference\u002Fdesign-considerations\u002Finstance-configuration-related-problems","en\u002F6.reference\u002F8.design-considerations\u002F3.instance-configuration-related-problems","i-lucide-wrench",{"title":355,"path":356,"stem":357,"icon":358},"Overly Permissive Public Access","\u002Fen\u002Freference\u002Fdesign-considerations\u002Foverly-permissive","en\u002F6.reference\u002F8.design-considerations\u002F4.overly-permissive","i-lucide-shield-off",{"title":360,"path":361,"stem":362,"icon":363},"No Aggregates","\u002Fen\u002Freference\u002Fdesign-considerations\u002Fno-aggregates","en\u002F6.reference\u002F8.design-considerations\u002F5.no-aggregates","i-lucide-sigma",{"title":365,"path":366,"stem":367,"icon":368},"Cross-Data-Source Referential Integrity","\u002Fen\u002Freference\u002Fdesign-considerations\u002Fcross-data-source-referential-integrity","en\u002F6.reference\u002F8.design-considerations\u002F6.cross-data-source-referential-integrity","i-lucide-unlink",{"title":370,"path":371,"stem":372,"icon":373},"CLI","\u002Fen\u002Freference\u002Fcli","en\u002F6.reference\u002F9.cli","i-lucide-square-terminal",{"title":221,"path":375,"stem":376,"children":377,"page":6},"\u002Fen\u002Freference\u002Fextensions","en\u002F6.reference\u002F9.extensions",[378,383,386,405],{"title":379,"path":380,"stem":381,"icon":382},"Extension Config and Manifest","\u002Fen\u002Freference\u002Fextensions\u002Fmanifest","en\u002F6.reference\u002F9.extensions\u002F1.manifest","i-lucide-file-json",{"title":370,"path":384,"stem":385,"icon":86},"\u002Fen\u002Freference\u002Fextensions\u002Fcli","en\u002F6.reference\u002F9.extensions\u002F2.cli",{"title":387,"path":388,"stem":389,"children":390,"page":6},"Extension Kit","\u002Fen\u002Freference\u002Fextensions\u002Fextension-kit","en\u002F6.reference\u002F9.extensions\u002F3.extension-kit",[391,395,400],{"title":392,"path":393,"stem":394,"icon":81},"Data Connector","\u002Fen\u002Freference\u002Fextensions\u002Fextension-kit\u002Fdata-connector","en\u002F6.reference\u002F9.extensions\u002F3.extension-kit\u002F1.data-connector",{"title":396,"path":397,"stem":398,"icon":399},"Protocol","\u002Fen\u002Freference\u002Fextensions\u002Fextension-kit\u002Fprotocol","en\u002F6.reference\u002F9.extensions\u002F3.extension-kit\u002F2.protocol","i-lucide-arrow-left-right",{"title":401,"path":402,"stem":403,"icon":404},"Schema Helpers","\u002Fen\u002Freference\u002Fextensions\u002Fextension-kit\u002Fexperimental","en\u002F6.reference\u002F9.extensions\u002F3.extension-kit\u002F3.experimental","i-lucide-blocks",{"title":113,"path":406,"stem":407,"children":408,"page":6},"\u002Fen\u002Freference\u002Fextensions\u002Fdata-connectors","en\u002F6.reference\u002F9.extensions\u002F4.data-connectors",[409,413,417,421,426,431],{"title":410,"path":411,"stem":412,"icon":81},"Data Connector API","\u002Fen\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fapi","en\u002F6.reference\u002F9.extensions\u002F4.data-connectors\u002F1.api",{"title":414,"path":415,"stem":416,"icon":176},"Operations and Operators","\u002Fen\u002Freference\u002Fextensions\u002Fdata-connectors\u002Foperations","en\u002F6.reference\u002F9.extensions\u002F4.data-connectors\u002F2.operations",{"title":148,"path":418,"stem":419,"icon":420},"\u002Fen\u002Freference\u002Fextensions\u002Fdata-connectors\u002Ferrors","en\u002F6.reference\u002F9.extensions\u002F4.data-connectors\u002F3.errors","i-lucide-triangle-alert",{"title":422,"path":423,"stem":424,"icon":425},"Runtime Limits","\u002Fen\u002Freference\u002Fextensions\u002Fdata-connectors\u002Flimits","en\u002F6.reference\u002F9.extensions\u002F4.data-connectors\u002F4.limits","i-lucide-gauge",{"title":427,"path":428,"stem":429,"icon":430},"Limitations","\u002Fen\u002Freference\u002Fextensions\u002Fdata-connectors\u002Flimitations","en\u002F6.reference\u002F9.extensions\u002F4.data-connectors\u002F5.limitations","i-lucide-ban",{"title":432,"path":433,"stem":434,"icon":435},"Network Permissions","\u002Fen\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fpermissions","en\u002F6.reference\u002F9.extensions\u002F4.data-connectors\u002F6.permissions","i-lucide-shield-check",{"title":437,"icon":121,"path":438,"stem":439,"children":440,"page":6},"Release Notes","\u002Fen\u002Frelease-notes","en\u002F7.release-notes",[441],{"title":442,"path":443,"stem":444,"icon":121},"Changelog","\u002Fen\u002Frelease-notes\u002Fchangelog","en\u002F7.release-notes\u002F1.changelog",{"id":446,"title":447,"body":448,"description":1868,"extension":1869,"links":1870,"meta":1871,"navigation":1872,"path":428,"seo":1873,"stem":429,"__hash__":1874},"docs_en\u002Fen\u002F6.reference\u002F9.extensions\u002F4.data-connectors\u002F5.limitations.md","Data Connector Limitations",{"type":449,"value":450,"toc":1812},"minimark",[451,454,458,473,499,503,508,511,536,540,543,555,559,563,574,591,595,637,655,659,663,677,693,697,704,720,724,735,752,756,759,884,892,927,952,978,982,986,1001,1025,1029,1043,1077,1081,1085,1091,1108,1112,1126,1148,1152,1161,1201,1205,1225,1240,1244,1248,1251,1263,1267,1275,1287,1291,1312,1332,1336,1339,1360,1364,1367,1395,1398,1402,1413,1425,1429,1445,1477,1481,1485,1488,1503,1507,1514,1529,1533,1545,1560,1564,1567,1588,1592,1596,1599,1615,1619,1622,1663,1667,1670,1682,1686,1689,1709,1713,1728,1747,1751,1757,1765,1777,1781],[452,453],"preview",{},[455,456,143],"h2",{"id":457},"overview",[459,460,461,462,466,467,472],"p",{},"Each entry below names a limitation, what callers and connectors observe when an ",[463,464,465],"strong",{},"external data source"," (the API, service, or database a data connector extension reads and writes) runs into it, and the workaround. Run the ",[468,469,471],"a",{"href":470},"\u002Fdeveloper\u002Fextensions\u002Fdata-connectors#fit-check","Fit Check"," first to find the entries that apply to your external data source.",[459,474,475,476,479,480,484,485,489,490,493,494,498],{},"A ",[463,477,478],{},"data source"," is the connector configured in a ",[468,481,483],{"href":482},"\u002Fconcepts\u002Forganization#glossary","workspace",". It exposes the external data source as ",[468,486,488],{"href":487},"\u002Fconcepts\u002Fdata-model#collections","collections",". A collection holds ",[463,491,492],{},"items",", each a single data object with named values called ",[468,495,497],{"href":496},"\u002Fconcepts\u002Fdata-model#fields","fields",".",[455,500,502],{"id":501},"required-filters","Required Filters",[504,505,507],"h3",{"id":506},"no-required-alternative-or-bounded-filters","No Required, Alternative, or Bounded Filters",[459,509,510],{},"A connector can't declare that a filter is required. It can't require one of several filters (e.g., \"channel or id\"), or bound a range (e.g., \"at most 7 days\"). Every declared operator is optional and can appear anywhere in the filter.",[512,513,514,521],"ul",{},[515,516,517,520],"li",{},[463,518,519],{},"What happens:"," callers can send an unfiltered or unbounded read, and Studio offers it. The connector has to refuse it at runtime.",[515,522,523,526,527,531,532,535],{},[463,524,525],{},"Workaround:"," refuse before making any request to the external data source. Throw ",[528,529,530],"code",{},"QueryRejected"," with a message that names the missing filter, and document the requirement for your users. The caller gets ",[528,533,534],{},"422"," \"The data source rejected the query\", with your message nested inside.",[504,537,539],{"id":538},"no-filters-across-relations","No Filters Across Relations",[459,541,542],{},"Callers can't filter a connector collection by fields of a related collection (e.g., issues by their team's name), even when the external data source could. The same holds the other way: a collection in another data source can't be filtered through a relation into a connector collection.",[512,544,545,550],{},[515,546,547,549],{},[463,548,519],{}," relation filters aren't offered on data connector collections. That includes permission rules: a rule can't filter through a relation that touches a connector collection.",[515,551,552,554],{},[463,553,525],{}," expose the foreign key as a filterable field, and have callers filter by it directly.",[455,556,558],{"id":557},"paging","Paging",[504,560,562],{"id":561},"offset-paging-only","Offset Paging Only",[459,564,565,566,569,570,573],{},"Engine and Studio page with ",[528,567,568],{},"limit"," and ",[528,571,572],{},"offset",". The contract has no cursor paging.",[512,575,576,584],{},[515,577,578,580,581,583],{},[463,579,519],{}," on an external data source that pages only by cursor, your connector has to walk its pages and discard items until it reaches ",[528,582,572],{},". The cost grows with the page number.",[515,585,586,588,589,498],{},[463,587,525],{}," cap how deep the connector walks, and refuse offsets beyond the cap with ",[528,590,530],{},[504,592,594],{"id":593},"no-declarable-page-size-or-depth-limit","No Declarable Page Size or Depth Limit",[459,596,597,598,600,601,603,604,606,607,610,611,614,615,619,620,623,624,626,627,629,630,633,634,636],{},"A connector can't declare a maximum ",[528,599,568],{}," or a maximum ",[528,602,572],{},". A caller's read without a ",[528,605,568],{}," arrives with the default of the ",[463,608,609],{},"instance"," (your Monospace deployment), ",[528,612,613],{},"100"," unless ",[616,617],"env-var",{"name":618},"query_limit_default"," changes it. When ",[528,621,622],{},"readMany"," declares ",[528,625,568],{},", a caller can ask for a larger ",[528,628,568],{},", or for no limit. When the instance sets ",[616,631],{"name":632},"query_limit_max",", a larger ",[528,635,568],{}," is rejected and no limit means that maximum. The maximum doesn't cap the default.",[512,638,639,647],{},[515,640,641,643,644,646],{},[463,642,519],{}," the connector receives page sizes and offsets the external data source can't serve in one request. Returning fewer items than ",[528,645,568],{}," tells Engine there are no more items.",[515,648,649,651,652,654],{},[463,650,525],{}," page through the external data source until the requested ",[528,653,568],{}," is filled or it runs out. Refuse offsets past its maximum depth at runtime.",[455,656,658],{"id":657},"query-shapes","Query Shapes",[504,660,662],{"id":661},"filter-sort-page-select-relate-count","Filter, Sort, Page, Select, Relate, Count",[459,664,665,666,569,668,670,671,498],{},"The query API offers filters, sorting, ",[528,667,568],{},[528,669,572],{},", field selection, relations, and a total count, each where the collection declares it. It has no aggregation, grouping, full-text search, or vector search yet, for any data source. Keep up with what's coming on our ",[468,672,676],{"href":673,"rel":674},"https:\u002F\u002Ffeedback.monospace.io",[675],"nofollow","Roadmap",[512,678,679,684],{},[515,680,681,683],{},[463,682,519],{}," an external data source's search or aggregate endpoints can't be exposed as query features.",[515,685,686,688,689,692],{},[463,687,525],{}," map a search grammar onto the declared operators where it matches exactly (e.g., ",[528,690,691],{},"icontains"," for case-insensitive substring matching). Leave the rest undeclared.",[504,694,696],{"id":695},"operators-depend-on-the-field-type","Operators Depend on the Field Type",[459,698,699,700,703],{},"Engine executes only certain operators for each field type. For example, boolean, JSON, bytes, and geometry fields support only ",[528,701,702],{},"equals",", and text operators exist only on strings.",[512,705,706,711],{},[515,707,708,710],{},[463,709,519],{}," a declaration that uses an operator Engine can't execute on that field type fails data source creation, even when the external data source supports the operator.",[515,712,713,715,716,719],{},[463,714,525],{}," declare the intersection of what the external data source supports and what Engine executes. See ",[468,717,414],{"href":718},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Foperations"," for the per-type table.",[504,721,723],{"id":722},"a-count-without-a-total-is-dropped","A Count Without a Total Is Dropped",[459,725,726,727,730,731,734],{},"Declaring ",[528,728,729],{},"meta.totalCount"," doesn't guarantee callers a total. When the connector answers a count read without ",[528,732,733],{},"totalCount",", Engine leaves the total out of the caller's response instead of failing the request.",[512,736,737,742],{},[515,738,739,741],{},[463,740,519],{}," a caller that asked for a total gets none, and no error.",[515,743,744,746,747,749,750,498],{},[463,745,525],{}," answer every count read with ",[528,748,733],{},". When the external data source can't count a request, throw ",[528,751,530],{},[504,753,755],{"id":754},"engine-sends-shapes-you-didnt-declare","Engine Sends Shapes You Didn't Declare",[459,757,758],{},"Engine composes parts of the request itself:",[512,760,761,767,776,796,805,814,845,870],{},[515,762,763,764,766],{},"a default ",[528,765,568],{}," on a caller's read",[515,768,769,771,772,775],{},[528,770,702],{}," for a caller's shorthand ",[528,773,774],{},"{ field: value }",", and ascending order for a sort without a direction",[515,777,778,780,781,784,785,788,789,792,793],{},[528,779,702],{}," with ",[528,782,783],{},"null"," for a caller's ",[528,786,787],{},"_null: true",", and ",[528,790,791],{},"not"," around it for ",[528,794,795],{},"_null: false",[515,797,798,799,788,802,804],{},"permission rules joined with ",[528,800,801],{},"or",[528,803,791],{}," around field rules before an update",[515,806,807,808,810,811,813],{},"one read per distinct parent key for a to-many relation (a relation field that returns several related items), up to 16 at a time, each with the include's ",[528,809,568],{},", or the instance default (",[528,812,613],{},") when the caller sets none",[515,815,816,817,819,820,822,823,825,826,829,830,833,834,836,837,839,840,844],{},"one read without a ",[528,818,568],{}," for a to-one relation (a relation field that returns a single related item), and for a to-many include that resolves to no ",[528,821,568],{}," and no ",[528,824,572],{},": ",[528,827,828],{},"limit=-1"," or ",[528,831,832],{},"limit=0"," without ",[616,835],{"name":632},", or no ",[528,838,568],{}," on an instance that unsets its default (see ",[468,841,843],{"href":842},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fapi#relation-reads","Relation Reads",")",[515,846,847,848,852,853,855,856,829,859,780,862,865,866,844],{},"read-backs of updates, and, when the connector doesn't declare a write's ",[468,849,851],{"href":850},"\u002Freference\u002Fextensions\u002Fmanifest#capabilities","query capability",", ",[528,854,622],{}," calls by stable ID around it and ",[528,857,858],{},"updateMany",[528,860,861],{},"deleteMany",[528,863,864],{},"select: []"," in place of the caller's write (see ",[468,867,869],{"href":868},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Foperations#what-engine-sends","What Engine Sends",[515,871,872,873,569,876,879,880,623,882],{},"count reads, which carry ",[528,874,875],{},"count: true",[528,877,878],{},"limit: 0",". They arrive only when ",[528,881,622],{},[528,883,729],{},[459,885,886,887,569,889,891],{},"The defaults and the permission wrappers, ",[528,888,801],{},[528,890,791],{},", arrive whatever the collection declares. Engine doesn't check the comparisons inside the filters it sends against the called member's declaration either: a field read rule's condition can reach a bulk update or delete whose member doesn't declare its field. The declaration gates the rest:",[512,893,894,900,911,914,920],{},[515,895,896,897,899],{},"the shorthand arrives only where the field declares ",[528,898,702],{},";",[515,901,902,905,906,908,909,899],{},[528,903,904],{},"_null"," arrives only on a nullable field that declares ",[528,907,702],{},", in a filter that also declares ",[528,910,791],{},[515,912,913],{},"relation reads arrive only for a direction the target collection's filter offers;",[515,915,916,917,919],{},"read-backs arrive only on collections whose ",[528,918,622],{}," can carry them (Engine checks that when it creates the data source);",[515,921,922,923,623,925,498],{},"count reads arrive only when ",[528,924,622],{},[528,926,729],{},[459,928,929,930,933,934,937,938,941,942,944,945,947,948,498],{},"A relation read or read-back can also arrive undeclared, on a key that can't carry a declared filter. That's a single field whose type has no ",[528,931,932],{},"in"," (e.g., ",[528,935,936],{},"boolean","), or a key with an ",[528,939,940],{},"unsupported"," field. Only the lookup's own operator arrives there undeclared: ",[528,943,932],{}," on a single field, or ",[528,946,702],{}," on each of several. See ",[468,949,951],{"href":950},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Foperations#rules-for-engines-own-calls","Rules for Engine's Own Calls",[512,953,954,959],{},[515,955,956,958],{},[463,957,519],{}," the connector receives filters and arguments beyond what a caller typed.",[515,960,961,963,964,966,967,970,971,973,974,498],{},[463,962,525],{}," handle these shapes, or refuse the ones you can't serve with ",[528,965,530],{},". They're valid requests, so don't refuse them with a plain ",[528,968,969],{},"Error",", which marks a request outside the declaration. Refuse any other undeclared comparison with a plain ",[528,972,969],{},", and never drop it. See ",[468,975,977],{"href":976},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fapi#handle-requests-you-didnt-declare","Handle Requests You Didn't Declare",[455,979,981],{"id":980},"keys","Keys",[504,983,985],{"id":984},"single-item-operations-need-a-single-field-primary-key","Single-Item Operations Need a Single-Field Primary Key",[459,987,988,852,991,852,994,997,998,1000],{},[528,989,990],{},"readOne",[528,992,993],{},"updateOne",[528,995,996],{},"deleteOne",", and item URLs need a primary key made of one field, of a type Engine supports (not ",[528,999,940],{},"). A collection keyed by several fields in the external data source (e.g., channel and timestamp) has none of them.",[512,1002,1003,1012],{},[515,1004,1005,1007,1008,1011],{},[463,1006,519],{}," a declaration of a ",[528,1009,1010],{},"*One"," operation on that collection makes Engine reject any data source creation or reintrospection that includes the collection. Without those operations, the collection has no item routes. A unique index isn't enough.",[515,1013,1014,1016,1017,1020,1021,1024],{},[463,1015,525],{}," declare a synthetic single-field primary key that encodes the parts reversibly (e.g., ",[528,1018,1019],{},"\"\u003Cchannel>:\u003Ctimestamp>\"",", escaping ",[528,1022,1023],{},":"," inside a part). Keep the parts as separate filterable fields, and decode the key back into the lookup it stands for.",[504,1026,1028],{"id":1027},"_64-bit-integers-arrive-as-strings","64-Bit Integers Arrive as Strings",[459,1030,1031,1032,569,1035,1038,1039,1042],{},"Engine sends ",[528,1033,1034],{},"int64",[528,1036,1037],{},"uint64"," values as decimal strings, in item data, filter values and keys, so they stay exact beyond JavaScript's safe-integer range. It accepts a string or a number back, and returns them to callers as strings (e.g., ",[528,1040,1041],{},"\"balance\": \"0\"","). Narrower integers stay numbers, and so do the elements of a list field: only single values become strings.",[512,1044,1045,1057],{},[515,1046,1047,1049,1050,1053,1054,1056],{},[463,1048,519],{}," a connector that checks ",[528,1051,1052],{},"typeof key === 'number'"," on an ",[528,1055,1034],{}," key treats every key as a miss, and a comparison with a number literal never matches.",[515,1058,1059,1061,1062,1064,1065,1068,1069,1072,1073,498],{},[463,1060,525],{}," read ",[528,1063,1034],{}," values as strings, and convert them with ",[528,1066,1067],{},"BigInt"," where you compute with them. Declare ",[528,1070,1071],{},"int32"," when the external data source's values fit 32 bits and callers should get numbers. See ",[468,1074,1076],{"href":1075},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fapi#values","Values",[455,1078,1080],{"id":1079},"relations","Relations",[504,1082,1084],{"id":1083},"each-relation-direction-needs-a-filter-on-its-target","Each Relation Direction Needs a Filter on Its Target",[459,1086,1087,1088,1090],{},"A relation has two sides (e.g., an article's author and an author's articles). Engine resolves each side by filtering the target collection by the relation's key fields. Each side is offered only when its target declares that filter, except for keys that can't carry one (see ",[468,1089,951],{"href":950},").",[512,1092,1093,1098],{},[515,1094,1095,1097],{},[463,1096,519],{}," if the external data source can't filter by the referencing field (e.g., list articles by author), that side of the relation can't be read. The other side still works when its own target can filter.",[515,1099,1100,1102,1103,1107],{},[463,1101,525],{}," declare the filter and output each side needs. See ",[468,1104,1106],{"href":1105},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Foperations#resolve-relations","Resolve Relations",". If neither side can be served, expose the reference as a plain field.",[504,1109,1111],{"id":1110},"unservable-relations-narrow-without-an-error","Unservable Relations Narrow Without an Error",[459,1113,1114,1115,569,1118,1121,1122,498],{},"A relation the declaration can't fully carry isn't rejected. Data source creation succeeds, and Engine offers less of it. Depending on what's missing, the relation can't be read or filtered, or is missing from one operation's results. It can also lose nested writes, including ",[528,1116,1117],{},"_create",[528,1119,1120],{},"_connect"," on a one-to-one relation under an update. See ",[468,1123,1125],{"href":1124},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Foperations#declare-nested-writes","Declare Nested Writes",[512,1127,1128,1143],{},[515,1129,1130,1132,1133,852,1136,1139,1140,498],{},[463,1131,519],{}," only a warning in the Engine log reports it, containing ",[528,1134,1135],{},"is not offered",[528,1137,1138],{},"offers no nested",", or ",[528,1141,1142],{},"can be neither read",[515,1144,1145,1147],{},[463,1146,525],{}," after creating a data source, check the workspace's OpenAPI document for every relation you declared, and search the Engine log for those phrases.",[504,1149,1151],{"id":1150},"foreign-keys-are-set-through-the-relation-on-create","Foreign Keys Are Set Through the Relation on Create",[459,1153,1154,1155,1157,1158,1160],{},"Create input doesn't accept a relation's foreign-key field. Callers set it on the relation instead, with ",[528,1156,1120],{}," and the target's key or ",[528,1159,1117],{}," for a new target, where the target collection offers them.",[512,1162,1163,1189],{},[515,1164,1165,1167,1168,1170,1171,1173,1174,1177,1178,1181,1182,1184,1185,1188],{},[463,1166,519],{}," when the foreign key sits on the created item, Engine passes the ",[528,1169,1120],{}," key to the connector without checking that the target exists. The external data source decides whether to accept it. When the key sits on the target instead, ",[528,1172,1120],{}," fails unless every target item exists. A non-nullable relation whose key sits on the created item is required on create. The exception is a foreign key whose fields all have an ",[528,1175,1176],{},"engineManaged"," ",[528,1179,1180],{},"onCreate"," default that yields a value, on a relation that offers ",[528,1183,1120],{},": Engine then connects that value itself. A ",[528,1186,1187],{},"connectorManaged"," default doesn't lift the requirement.",[515,1190,1191,1193,1194,1197,1198,1200],{},[463,1192,525],{}," when the external data source refuses a write that names a missing item, throw ",[528,1195,1196],{},"ForeignKeyConstraintViolation",", so the caller gets ",[528,1199,534],{},". For references whose target often doesn't exist in the external data source (e.g., an external phone number), expose the reference as a plain field rather than a relation.",[504,1202,1204],{"id":1203},"relation-key-types-must-match","Relation Key Types Must Match",[459,1206,1207,1208,1211,1212,852,1215,1211,1217,788,1219,1211,1222,498],{},"The schema helpers require scalar key fields with the same type name on both ends of a relation. For example, ",[528,1209,1210],{},"uuid"," doesn't relate to ",[528,1213,1214],{},"string",[528,1216,1071],{},[528,1218,1034],{},[528,1220,1221],{},"date",[528,1223,1224],{},"dateTime",[512,1226,1227,1235],{},[515,1228,1229,1231,1232,498],{},[463,1230,519],{}," the schema helpers reject the schema with ",[528,1233,1234],{},"Incompatible relation keys",[515,1236,1237,1239],{},[463,1238,525],{}," declare both key fields with the same type, converting values in the connector.",[455,1241,1243],{"id":1242},"writes","Writes",[504,1245,1247],{"id":1246},"no-transactions","No Transactions",[459,1249,1250],{},"Engine runs no transaction across connector calls, and has nothing to roll back in the external data source. Whether a single request to it is atomic depends on the external data source.",[512,1252,1253,1258],{},[515,1254,1255,1257],{},[463,1256,519],{}," when a multi-item update, a nested write, or another multi-step write fails partway, the steps before the failure stay applied. So do your connector's writes when Engine rejects its answer afterwards (e.g., an item missing a selected field).",[515,1259,1260,1262],{},[463,1261,525],{}," design writes to be safe to retry, and don't rely on rollbacks.",[504,1264,1266],{"id":1265},"bulk-writes-are-only-as-atomic-as-the-external-data-source","Bulk Writes Are Only as Atomic as the External Data Source",[459,1268,1269,1270,829,1272,1274],{},"When the external data source writes one item at a time, a filter-based ",[528,1271,858],{},[528,1273,861],{}," has to find the matching items first and then write each one.",[512,1276,1277,1282],{},[515,1278,1279,1281],{},[463,1280,519],{}," a concurrent writer can change an item between the read and the write. A write that fails partway leaves the items before it written, and the error has only its message to say how many.",[515,1283,1284,1286],{},[463,1285,525],{}," use the external data source's conditional or idempotent write features where it has them. Start no new write after the first failure, and say in the message how far the write got. The Stripe example keeps the error's class and prefixes its message: \"Deleted 3 of 4 products before this error: This product cannot be deleted because it has one or more user-created prices.\"",[504,1288,1290],{"id":1289},"writes-without-query-capabilities-take-several-calls","Writes Without Query Capabilities Take Several Calls",[459,1292,1293,1294,1296,1297,1300,1301,829,1303,1305,1306,1308,1309,1311],{},"A connector that doesn't declare a write's ",[468,1295,851],{"href":850}," makes Engine add calls of its own. A ",[528,1298,1299],{},"create"," answers only the stable IDs, and Engine reads the created items back. An update or delete goes through ",[528,1302,858],{},[528,1304,861],{}," by stable ID, between ",[528,1307,622],{}," calls. See ",[468,1310,869],{"href":868}," for each sequence.",[512,1313,1314,1323],{},[515,1315,1316,1318,1319,1322],{},[463,1317,519],{}," every such write costs extra connector calls, and each call your connector serves can cost requests to the external data source. Another writer can change an item between the calls, and an external data source that is only eventually consistent can answer the read-back with stale data. Each collection with such a write needs a stable ID and declarations that carry the extra calls. Without ",[528,1320,1321],{},"updateReturning",", no update can change a stable-ID field.",[515,1324,1325,1327,1328,498],{},[463,1326,525],{}," declare the capabilities your connector can keep, so Engine uses the write's answer instead of reading the items itself. Permission rules and relation fields can still add reads. See ",[468,1329,1331],{"href":1330},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Foperations#declare-query-capabilities","Declare Query Capabilities",[504,1333,1335],{"id":1334},"no-field-level-value-rules","No Field-Level Value Rules",[459,1337,1338],{},"A field can't declare the values it accepts (e.g., an enum, or \"may only be cleared\").",[512,1340,1341,1346],{},[515,1342,1343,1345],{},[463,1344,519],{}," the connector has to refuse invalid values at runtime.",[515,1347,1348,1350,1351,1354,1355,1357,1358,498],{},[463,1349,525],{}," validate values in ",[528,1352,1353],{},"query"," before calling the external data source, and throw ",[528,1356,530],{}," with a message that names the field and the accepted values. The caller gets ",[528,1359,534],{},[504,1361,1363],{"id":1362},"answers-are-only-partly-checked","Answers Are Only Partly Checked",[459,1365,1366],{},"Engine converts each value your connector returns by its field's type, but doesn't enforce every declared constraint.",[512,1368,1369,1385],{},[515,1370,1371,1373,1374,1376,1377,1380,1381,1384],{},[463,1372,519],{}," a ",[528,1375,783],{}," passes for a non-nullable field, and a value that exceeds a narrower integer width (e.g., ",[528,1378,1379],{},"int8","), a fixed string length, or a decimal's declared precision and scale passes too. A ",[528,1382,1383],{},"geometry"," field is the reverse: Engine can't convert geometry values yet, so any non-null value in it fails the request.",[515,1386,1387,1389,1390,1394],{},[463,1388,525],{}," return only values that fit the declaration. See ",[468,1391,1393],{"href":1392},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fapi#answer-a-query","Answer a Query"," for what Engine does check.",[455,1396,148],{"id":1397},"errors",[504,1399,1401],{"id":1400},"no-automatic-retries","No Automatic Retries",[459,1403,1404,1405,1408,1409,1412],{},"Engine doesn't retry a failed connector call, and ",[528,1406,1407],{},"RateLimited"," carries only a message. Engine answers it without a ",[528,1410,1411],{},"Retry-After"," header.",[512,1414,1415,1420],{},[515,1416,1417,1419],{},[463,1418,519],{}," a throttled request to the external data source fails the caller's request.",[515,1421,1422,1424],{},[463,1423,525],{}," retry inside the connector where the request is safe to repeat, with a small, bounded number of attempts. Put the wait into the message, as the example connectors do: \"Stripe rate limited the connector. Retry after 2 seconds.\"",[504,1426,1428],{"id":1427},"engine-doesnt-check-credentials","Engine Doesn't Check Credentials",[459,1430,1431,1432,1435,1436,852,1439,788,1442,1444],{},"Engine runs the connector's ",[528,1433,1434],{},"testConnection"," on a connection test, and before it creates a data source or previews its schema. Engine itself never checks a credential. A connector whose ",[528,1437,1438],{},"setup",[528,1440,1441],{},"introspect",[528,1443,1434],{}," make no authenticated request to the external data source accepts any credential.",[512,1446,1447,1469],{},[515,1448,1449,1451,1452,852,1454,569,1456,1458,1459,1461,1462,1464,1465,1468],{},[463,1450,519],{}," when none of ",[528,1453,1438],{},[528,1455,1441],{},[528,1457,1434],{}," makes an authenticated request, a data source with a wrong credential is created. It fails once the connector first makes a request that needs the credential. A connector without ",[528,1460,1434],{}," still creates, and a connection test answers ",[528,1463,534],{}," code ",[528,1466,1467],{},"7002",", \"The connector does not offer a connection test\".",[515,1470,1471,1473,1474,1476],{},[463,1472,525],{}," implement ",[528,1475,1434],{}," with an authenticated read from the external data source.",[455,1478,1480],{"id":1479},"configuration-and-network","Configuration and Network",[504,1482,1484],{"id":1483},"configuration-and-permissions-are-fixed-at-creation","Configuration and Permissions Are Fixed at Creation",[459,1486,1487],{},"No API changes an existing data source's configuration or granted permissions. Reintrospecting keeps the original configuration and grant. We're working on letting you change a data source's configuration after it's created.",[512,1489,1490,1495],{},[515,1491,1492,1494],{},[463,1493,519],{}," rotating a credential or changing a host requires a new data source, with a new id.",[515,1496,1497,1177,1499,498],{},[463,1498,525],{},[468,1500,1502],{"href":1501},"\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Fdata-sources#recreate-a-data-source","recreate the data source",[504,1504,1506],{"id":1505},"grants-must-match-the-required-permissions-exactly","Grants Must Match the Required Permissions Exactly",[459,1508,1509,1510,1513],{},"A data source starts only when its granted permissions exactly match the permissions the manifest and ",[528,1511,1512],{},"preflight"," require together. That means the same hosts, ports, and wildcards. Reasons aren't compared.",[512,1515,1516,1521],{},[515,1517,1518,1520],{},[463,1519,519],{}," a new connector version that changes the combined set of required permissions stops each existing data source that uses it, at the next request that reaches its connector. From then on the data source refuses every request that reaches its connector. Cached results are still served.",[515,1522,1523,1177,1525,1528],{},[463,1524,525],{},[468,1526,1527],{"href":1501},"recreate those data sources"," and approve the new permissions, or reinstall a connector version whose required permissions match the stored grant.",[504,1530,1532],{"id":1531},"hosts-must-be-known-up-front","Hosts Must Be Known Up Front",[459,1534,1535,1536,1538,1539,1139,1542,498],{},"The sandbox allows only the hosts in the manifest plus those ",[528,1537,1512],{}," derives from configuration, each as a host, ",[528,1540,1541],{},"host:port",[528,1543,1544],{},"*.host",[512,1546,1547,1552],{},[515,1548,1549,1551],{},[463,1550,519],{}," a request to any other host fails, including redirects to hosts you didn't predict (e.g., a regional host or a download CDN).",[515,1553,1554,1556,1557,498],{},[463,1555,525],{}," name those hosts, or a wildcard that covers them, in the manifest. See ",[468,1558,432],{"href":1559},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fpermissions",[504,1561,1563],{"id":1562},"configuration-isnt-validated-by-engine","Configuration Isn't Validated by Engine",[459,1565,1566],{},"Engine passes the configuration JSON to the connector unchecked. Studio shows it as a raw JSON editor.",[512,1568,1569,1576],{},[515,1570,1571,1573,1574,498],{},[463,1572,519],{}," typos and missing keys reach ",[528,1575,1438],{},[515,1577,1578,1580,1581,1583,1584,1587],{},[463,1579,525],{}," parse and validate the configuration in ",[528,1582,1438],{},", and throw ",[528,1585,1586],{},"InvalidConfiguration"," with a message that names the problem.",[455,1589,1591],{"id":1590},"lifecycle","Lifecycle",[504,1593,1595],{"id":1594},"data-sources-keep-the-schema-from-creation","Data Sources Keep the Schema From Creation",[459,1597,1598],{},"A data source keeps the schema it was created or last reintrospected with. Installing a connector version with a changed schema doesn't update it.",[512,1600,1601,1606],{},[515,1602,1603,1605],{},[463,1604,519],{}," Engine keeps accepting requests based on the old schema. Requests the new code can't serve fail, and renamed collections keep their old names.",[515,1607,1608,1177,1610,1614],{},[463,1609,525],{},[468,1611,1613],{"href":1612},"\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Fdata-sources#update-data-sources-after-an-extension-update","refresh the schema or recreate"," each data source after changing its declared schema.",[504,1616,1618],{"id":1617},"no-schema-changes-from-monospace","No Schema Changes from Monospace",[459,1620,1621],{},"The connector declares the schema, so Monospace can't add, change, or remove collections, fields or namespaces on a data connector data source, or relations whose pointing fields are on one of its collections. A relation whose pointing fields live in another data source falls under that data source's rules. API names are Monospace's own, so those stay editable.",[512,1623,1624,1658],{},[515,1625,1626,1373,1628,1632,1633,569,1639,780,1645,1648,1649,788,1651,1657],{},[463,1627,519],{},[468,1629,1631],{"href":1630},"\u002Freference\u002Fapi-reference\u002Fschema-migration","schema migration"," that changes the data source's schema fails. Operations that change only an API name succeed: ",[468,1634,1636],{"href":1635},"\u002Freference\u002Fapi-reference\u002Fschema-migration\u002Foperation-reference#rename-a-collection",[528,1637,1638],{},"renameCollection",[468,1640,1642],{"href":1641},"\u002Freference\u002Fapi-reference\u002Fschema-migration\u002Foperation-reference#rename-a-field",[528,1643,1644],{},"renamePrimitiveField",[528,1646,1647],{},"dbName"," set to ",[528,1650,783],{},[468,1652,1654],{"href":1653},"\u002Freference\u002Fapi-reference\u002Fschema-migration\u002Foperation-reference#rename-a-relation-field",[528,1655,1656],{},"renameRelationField",". The connector keeps receiving its own names.",[515,1659,1660,1662],{},[463,1661,525],{}," change the schema in the connector, then reintrospect the data source.",[504,1664,1666],{"id":1665},"engine-upgrades-can-disable-connector-collections","Engine Upgrades Can Disable Connector Collections",[459,1668,1669],{},"When a newer Engine can't use a stored declaration, it loads the collection with no operations and logs an error that says to reintrospect the source.",[512,1671,1672,1677],{},[515,1673,1674,1676],{},[463,1675,519],{}," the affected collections can't be queried until you reintrospect each data source.",[515,1678,1679,1681],{},[463,1680,525],{}," after an Engine upgrade, check the log and reintrospect the data sources it names. If reintrospection is refused, update the connector so its declaration passes the newer rules first.",[504,1683,1685],{"id":1684},"collection-names-are-shared-per-workspace","Collection Names Are Shared per Workspace",[459,1687,1688],{},"Collection names from all data sources in a workspace share one namespace.",[512,1690,1691,1704],{},[515,1692,1693,1695,1696,1699,1700,1703],{},[463,1694,519],{}," when a collection's derived API name is already taken, Engine picks a different one, with a prefix or a numeric suffix (e.g., ",[528,1697,1698],{},"customers_2","). An explicit ",[528,1701,1702],{},"apiName"," is kept as declared.",[515,1705,1706,1708],{},[463,1707,525],{}," give collections distinctive names in the connector.",[504,1710,1712],{"id":1711},"naming-style-can-be-mixed","Naming Style Can Be Mixed",[459,1714,1715,1716,1719,1720,1723,1724,1727],{},"Engine derives collection and field API names from ",[528,1717,1718],{},"name"," using the workspace's naming convention. The default is camelCase (e.g., ",[528,1721,1722],{},"unit_amount"," becomes ",[528,1725,1726],{},"unitAmount","). Relation names are used exactly as declared.",[512,1729,1730,1735],{},[515,1731,1732,1734],{},[463,1733,519],{}," declarations in a different style produce an API that mixes both styles.",[515,1736,1737,1739,1740,1742,1743,498],{},[463,1738,525],{}," declare names in the workspace's convention, or set an explicit ",[528,1741,1702],{},". See ",[468,1744,1746],{"href":1745},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Foperations#name-collections-and-fields","Name Collections and Fields",[455,1748,1750],{"id":1749},"runtime","Runtime",[459,1752,1753,1754,1756],{},"Connectors run in a sandboxed Deno worker with web APIs, no Node APIs, no filesystem, and no persistence. Module loading and ",[528,1755,1438],{}," run under a timeout.",[459,1758,1759,1760,498],{},"Need a Node.js-compatible API? ",[468,1761,1764],{"href":1762,"rel":1763},"https:\u002F\u002Ffeedback.monospace.io\u002Frequest?request=new",[675],"Let us know",[459,1766,1767,1768,1771,1772,1776],{},"See ",[468,1769,237],{"href":1770},"\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Fruntime"," for the sandbox and ",[468,1773,1775],{"href":1774},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Flimits","Data Connector Runtime Limits"," for the numbers.",[455,1778,1780],{"id":1779},"see-also","See Also",[512,1782,1783,1789,1794,1801,1807],{},[515,1784,1785,1788],{},[468,1786,113],{"href":1787},"\u002Fdeveloper\u002Fextensions\u002Fdata-connectors",": live queries and the Fit Check",[515,1790,1791,1793],{},[468,1792,414],{"href":718},": the declaration rules Engine enforces",[515,1795,1796,1800],{},[468,1797,1799],{"href":1798},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Ferrors","Data Connector Errors",": the error classes and when to throw them",[515,1802,1803,1806],{},[468,1804,246],{"href":1805},"\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Fdata-source-mapping",": patterns for paging, filters, and keys",[515,1808,1809,1811],{},[468,1810,237],{"href":1770},": the sandbox and data source lifecycle",{"title":1813,"searchDepth":1814,"depth":1814,"links":1815},"",2,[1816,1817,1822,1826,1832,1836,1842,1849,1853,1859,1866,1867],{"id":457,"depth":1814,"text":143},{"id":501,"depth":1814,"text":502,"children":1818},[1819,1821],{"id":506,"depth":1820,"text":507},3,{"id":538,"depth":1820,"text":539},{"id":557,"depth":1814,"text":558,"children":1823},[1824,1825],{"id":561,"depth":1820,"text":562},{"id":593,"depth":1820,"text":594},{"id":657,"depth":1814,"text":658,"children":1827},[1828,1829,1830,1831],{"id":661,"depth":1820,"text":662},{"id":695,"depth":1820,"text":696},{"id":722,"depth":1820,"text":723},{"id":754,"depth":1820,"text":755},{"id":980,"depth":1814,"text":981,"children":1833},[1834,1835],{"id":984,"depth":1820,"text":985},{"id":1027,"depth":1820,"text":1028},{"id":1079,"depth":1814,"text":1080,"children":1837},[1838,1839,1840,1841],{"id":1083,"depth":1820,"text":1084},{"id":1110,"depth":1820,"text":1111},{"id":1150,"depth":1820,"text":1151},{"id":1203,"depth":1820,"text":1204},{"id":1242,"depth":1814,"text":1243,"children":1843},[1844,1845,1846,1847,1848],{"id":1246,"depth":1820,"text":1247},{"id":1265,"depth":1820,"text":1266},{"id":1289,"depth":1820,"text":1290},{"id":1334,"depth":1820,"text":1335},{"id":1362,"depth":1820,"text":1363},{"id":1397,"depth":1814,"text":148,"children":1850},[1851,1852],{"id":1400,"depth":1820,"text":1401},{"id":1427,"depth":1820,"text":1428},{"id":1479,"depth":1814,"text":1480,"children":1854},[1855,1856,1857,1858],{"id":1483,"depth":1820,"text":1484},{"id":1505,"depth":1820,"text":1506},{"id":1531,"depth":1820,"text":1532},{"id":1562,"depth":1820,"text":1563},{"id":1590,"depth":1814,"text":1591,"children":1860},[1861,1862,1863,1864,1865],{"id":1594,"depth":1820,"text":1595},{"id":1617,"depth":1820,"text":1618},{"id":1665,"depth":1820,"text":1666},{"id":1684,"depth":1820,"text":1685},{"id":1711,"depth":1820,"text":1712},{"id":1749,"depth":1814,"text":1750},{"id":1779,"depth":1814,"text":1780},"Review what a data connector extension can't do today, what happens when an external data source needs it, and how to work around it.","md",null,{},{"title":427,"icon":430},{"title":447,"description":1868},"buZbtR9gi9v1x9mx8G82EYoC_EaXX4t7TdRy9kVDBlg",[1876,1878],{"title":422,"path":423,"stem":424,"description":1877,"icon":425,"children":-1},"Hard numbers and fixed rules for data connector extensions at runtime, and the error or behavior each one produces.",{"title":432,"path":433,"stem":434,"description":1879,"icon":435,"children":-1},"Learn how data connector entries declare net permissions, how Monospace derives the set a data source needs, and how to approve it when you create one.",1790840088666]