Diese Seite beschreibt kombinierbare Berichte: das Ergebnis eines Berichts wird eine Tabelle, die ein anderer Bericht abfragen kann, und ein Treiber kann alles fronten, was Zeilen zurückgibt. Es ist eine Designaufzeichnung; §8 benennt die Phasen, und nicht alle sind gebaut.
Umfang: die Architektur, die der Benutzer am 2026-11-22 beschrieb: ein Benutzer entwirft einen Bericht gegen eine Datenquelle (MySQL, SQL Server, PostgreSQL, SQLite oder eine Web-API wie die Seller API von eBay); das Ergebnis dieses Berichts ist eine materialisierte SQLite-Tabelle; und ein anderer Bericht kann eine Abfrage gegen diesen Bericht entwerfen — die Ausgabe eines Berichts mit der Ausgabe eines anderen Berichts und mit Basisquellen in einem Abfragegraphen joinen. Beim Refresh durchläuft die Engine den Graphen von unten nach oben, führt jedes Blatt gegen seine eigene Quelle aus, materialisiert jedes Ergebnis und führt schließlich die komponierende Abfrage über die Materialisierungen aus. Die Naht für Nicht-SQL-Treiber ist Teil davon: ein Treiber, der eine API frontet, erhält eine strukturierte Abfrage, keinen SQL-Text, und gibt Zeilen in Tabellenform zurück.
Datum: 2026-11-22, gelesen bei eba4225a1; Entscheidungen eingearbeitet am 2026-11-22 (§9.2).
Status: Designbericht. Er legt die Idee und das Design dar; er implementiert nichts und fügt TASKS.md keine Arbeit hinzu. Der Code-Audit, der die Datenobjekt-Hälfte begründet, ist MAD_DATA_OBJECT.md; die Richtung ist docs/vision.md. Dieses Dokument fügt das Kompositionsmodell für mehrere Quellen hinzu (zuerst Unterberichte innerhalb eines Dokuments), die Treiber-API, die Nicht-SQL-Quellen erstklassig macht, und eine kombinierte Phasenreihenfolge.
Ein Bericht ist eine Funktion von Datenquellen auf eine Tabelle. Die Unterscheidung zwischen Definition und Ergebnis, die für dieses Design zählt, steht bereits im Code:
.mad-Archiv.MADDataColumns) und Zeilen. Es lebt neben dem Dokument in einem begleitenden SQLite-Cache (.maddb + .mdcache), außerhalb des Archivs, weil es abgeleitet und regenerierbar ist.Die Erweiterung besteht darin, das Ergebnis als Tabelle adressierbar zu machen. Die Ausgabe eines Berichts wird dann eine Quelle für einen anderen Bericht, genau wie eine Schematabelle heute eine Quelle ist. Ein Bericht, der auf Berichten aufbaut, ist ein DAG abgeleiteter Tabellen: eine portable semantische Schicht, in der einen Bericht zu entwerfen auch heißt, eine wiederverwendbare Datenquelle zu entwerfen.
Dieselbe Erweiterung macht Berichte mit mehreren Quellen natürlich. Jedes Quellobjekt führt gegen seine eigene Datenbank oder API aus, mit seinem eigenen Treiber und eigenen Zugangsdaten, und materialisiert in seine eigene SQLite-Tabelle. Das komponierende Objekt führt gegen den lokalen Cache aus, nicht gegen einen entfernten Server, und joint die Materialisierungen. Es wird keine Föderations-Engine hinzugefügt; die Snapshots sind die Föderation.
Das Beispiel des Benutzers: ein Unternehmen möchte einen Bericht über seine eBay-Angebote. Ein Berichtsobjekt fragt die eBay Seller API ab und materialisiert die Angebote; ein anderes fragt die MySQL-Datenbank des Unternehmens nach Verkäufen ab; ein komponierender Bericht joint die beiden Ausgaben über SKU. Jeder Treiber kennt nur seine eigene Quelle. Der Join geschieht in SQLite, lokal.
Der Nicht-SQL-Treiber ist es, der das erste Objekt möglich macht. Sein Vertrag ist derselbe „Schema plus Zeilen“-Vertrag, den die SQL-Treiber erfüllen — aber seine Eingabe sollte der Abfragegraph sein, kein SQL-String, den er parsen muss.
Die teuren Teile existieren. MAD_DATA_OBJECT.md §3 ist der ausführliche Audit; die tragenden Fakten für diesen Bericht sind:
RptqQuery besitzt Tabellen, Felder, Links, Prädikate und Gruppen. MADModelDocument baut ein MADModelDatabase pro RptqQuery, mit der eigenen Anmerkung des Codes, dass aktuelle Versionen eines verwenden. Die Kardinalität ist eine Konvention der Abläufe der App, nicht des Speichers (MAD_DATA_OBJECT.md §3.1).MADQueryFull -copySQLWithManagedObjectContext:error: (MAD/Source/MADQueryFull.m:133-273) baut die SELECT-Liste, den FROM/JOIN-Baum aus einem topologisch sortierten Graphen, die WHERE-Klausel und das Limit, über die Dialekt-Haken des Treibers.MADDatabase ist executeSQL:fieldKeys:onConnection:intoResultTable:withError: (MADAPI/Source/MADDatabaseProtocol.h:33-34), und das Ziel ist jedes id <MADDataTableWriting>, keine konkrete Tabellenklasse. Alle vier Treiber füllen es auf dieselbe Weise: alle Objekte entfernen, Spalten hinzufügen, massenhaft einfügen, Zeilen hinzufügen.MADDataTableFast schreibt <tag>.maddb und die Tabelle t<tag> (MADSqlite3/Source/MADDataTableFast.m:403-406, :463-467, :503-511). Das Schema-Plist ist .mdcache; Zeilen und Schema sind trennbar (docs/05-companion-files.md §5). SQLite ist bereits ein Treiber (MADSqlite3/Source/MADDatabaseSqlite3.m), also ist eine Abfrage, deren „Datenbank“ der Cache ist, heutiger Code, kein neuer Code.docs/05-companion-files.md §5.2). Das ist richtig für ein abgeleitetes Artefakt, aber es ist eine Einschränkung für jedes Design, das den Cache eines anderen Berichts als Quelle behandelt: der Cache ist vielleicht nicht da.Derselbe Abschnitt benennt die drei Festverdrahtungspunkte der einen Abfrage, und sie gelten heute noch:
MADQueryFull liest die erste Datenbank und die erste Abfrage des Dokuments neu, statt die Abfrage zu verwenden, mit der es initialisiert wurde (MAD/Source/MADQueryFull.m:147-149).MADocument -dataTableForQuery: ist ein Ein-Slot-Schalter: es gibt die eine Tabelle des Dokuments für MADQueryFull und nil für alles andere zurück (MAD/Source/MADocument.m:873-880).MADQueryActiveQueryFields durchsucht jedes Element, jeden Link und jede Gruppe im Speicher ohne Abfragebereich (MAD/Source/MADQueryActiveQueryFields.m:27-100). Die Felder einer zweiten Abfrage würden in die SELECT-Liste der ersten Abfrage lecken.Zwei weitere Fakten zählen für das Kompositionsdesign:
initWithId: self.fileURL.lastPathComponent.hash (MAD/Source/MADocument.m:273-275), und das Cache-Verzeichnis wird nach diesem Hash benannt. Nichts kann die Tabelle über eine stabile Identität adressieren.MADDataTableFast ist eine Datei. filenameCacheMadDB ist <tag>.maddb (MADSqlite3/Source/MADDataTableFast.m:403-406), und jede Instanz öffnet ihre eigenen Einfüge- und Auswahlverbindungen (:482-501). Es gibt heute keinen Modus „mehrere Tabellen in einer .maddb“. MAD_DATA_OBJECT.md §5.1 beschreibt diesen Modus als Designvariante; die aktuelle Klasse implementiert ihn nicht.ATTACH-Unterstützung. Eine Suche in MADSqlite3, MAD und CLI findet keine Verwendung von ATTACH DATABASE. Dateiübergreifende Komposition braucht sie als Ergänzung oder einen Hineinkopierschritt.RptqDatabase (Treiber + Verbindung + Zugangsdaten) und eine Abfragedefinition. Es wird gegen seine Quelle ausgeführt.MAD/Source/MADQueryFull.m:170-204); der Objektgraph braucht dieselbe Disziplin auf Objektebene.Das Paging bleibt unverändert. Die Engine zieht weiterhin das vollständige Ergebnis in den lokalen Cache; die UI blättert über den Cache. Für einen API-Treiber ist „Pagination“ eine interne Schleife über die Seiten der API, um seine Materialisierung zu füllen; es ist kein Streaming- oder Paging-Vertrag mit der Engine. Die limit/offset des Plans existieren für Vorschauen im Design-Modus und für einen Treiber, der seinen Abruf begrenzen will, nicht für das Paging des Betrachters.
Gruppierung, Sortierung und Aggregate bleiben unverändert: sie werden über den lokalen Cache berechnet (MAD_DATA_OBJECT.md §3.5). Der Treiber gibt Detailzeilen zurück; er muss kein GROUP BY oder die Gruppierung des Berichts implementieren. Ein Sortierhinweis im Plan lässt einen Treiber eine Top-N-Anfrage nach unten durchreichen, wenn ein Limit vorhanden ist; die Engine sortiert trotzdem neu.
Der Instinkt des Benutzers war ATTACH, und der aktuelle Code macht es zum kürzeren Weg.
Layout A — eine .maddb pro Quellobjekt, ATTACH zum Joinen.
MADDataTableFast jedes Objekts behält seine eigene <tag>.maddb und t<tag>.ATTACH DATABASE '<path>' AS <alias> für jedes benötigte Quellobjekt aus.<alias>.t<tag>.ATTACH-Unterstützung in MADDatabaseSqlite3, Aliasverwaltung und Quoting von Pfaden. Die Klasse ist bereits ein vollständiger SQLite-Wrapper, also ist dies eine kleine Ergänzung.SQLITE_MAX_ATTACHED ist standardmäßig 10, und kein Buildrezept im Repository hebt es an (Compressor/sqlite3.xcconfig, Linux/, Windows/Engine/). Es anzuheben ist eine Buildänderung auf drei Plattformen. v1 behandelt mehr als zehn direkte Quellen als Fehler zur Designzeit..maddb, wie jedes andere Ergebnis.Layout B — mehrere Tabellen in einer .maddb.
t<tag>, kein ATTACH.MADDataTableFast von „eine Instanz besitzt eine Datei“ auf ein geteiltes Datei-/Verbindungsmodell umzustellen oder eine Tabellenregistratur darüber hinzuzufügen. Das ist eine größere Änderung als ATTACH und läuft dem aktuellen Ein-Datei-pro-Tabelle-Design der Klasse zuwider.Empfehlung: Layout A für die erste Kompositionsimplementierung, weil es der aktuellen Klassengrenze folgt und zum Modell des Benutzers passt. Layout B bleibt die sauberere langfristige Dateigeschichte, falls das Dateimodell pro Tabelle je überarbeitet wird.
Der Tabellenverweis einer komponierenden Abfrage braucht eine zweite Art neben databaseSchemaTable (dem heutigen RptqQueryTable.databaseSchemaTable, MAD/Source/rptq/autogen/RptqQueryTable.h:27). Die Entscheidung des Benutzers (2026-11-22) ist, dass Komposition zuerst innerhalb eines Dokuments geschieht: ein .mad-Dokument enthält mehrere Berichts-/Abfragedefinitionen — Unterberichte —, und der komponierende Bericht verweist über seine Identität auf einen davon. Die Eigenschaft einer einzigen portablen Datei bleibt erhalten, und das iOS-Problem der dateiübergreifenden Neuauthorisierung entsteht für v1 nicht. Ein Verweis auf einen Bericht in einer anderen .mad-Datei (eine Dokumentidentität plus ein Pfad) ist ein späteres, separates Anliegen, hinter der Komposition innerhalb desselben Dokuments zurückgestellt.
Der Cache ist pro Gerät und entbehrlich, also zeichnet der Verweis auf, was auszuführen ist, nicht wo die Daten sind:
.maddb/.mdcache) auf und verwendet sie wieder, statt das Kind erneut auszuführen. Eine Festschreibung ist ein aufbewahrtes Cache-Artefakt, nie im .mad eingebettete Daten — das Archiv bleibt definitionsonly (§6). Live und festgeschrieben lesen beide aus dem Cache-Verzeichnis; „pin“ heißt „diese Materialisierung behalten und wiederverwenden“, nicht „die Daten ins Dokument kopieren“.Die Benennung der Materialisierung wandert vom Dateinamen-Hash zu einer stabilen Objektidentität, sodass Dateien nicht kollidieren und ein Elternteil ein bestimmtes Kind adressieren kann (§3.6, §6).
RptqQueryField hat genau einen Feldverweis, databaseSchemaField (MAD/Source/rptq/autogen/RptqQueryField.h:27), und der Select-Builder, der Join-Builder, die Prädikate und die Join-UI lesen alle queryField.databaseSchemaField.name. Die Ausgabespalten eines Kindes sind MADDataColumns, keine Schemafelder. Die Empfehlung ist, eine Ergebnisschema-Tabelle und -Feldmenge pro Objekt aus den MADDataColumns des Kindes zu synthetisieren: die Abfragefelder des Elternteils zeigen dann auf gewöhnliche Schemafeldzeilen, und jeder vorhandene Builder und jede UI funktioniert unverändert. Die synthetischen Zeilen sind ein Snapshot des Ergebnisschemas des Kindes und werden aufgefrischt, wenn sich das Schema des Kindes ändert. Die Alternative — eine zweite Feldverweisart auf RptqQueryField — berührt jeden Builder und wird nicht empfohlen. Builder-Entscheidung.
Zur Designzeit braucht das Elternteil das Ergebnisschema des Kindes — Spaltennamen, Typen, Längen —, um die Join-UI zu zeichnen und Feldverweise zu validieren. Es sollte die Zeilen des Kindes nicht brauchen und auch nicht die Quellverbindung des Kindes. Das Schema ist dieselbe MADDataColumn-Beschreibung, die der Cache bereits serialisiert. Das ist die Hälfte „beschreiben ohne auszuführen“ des Datenobjekt-Vertrags; sie ist eine Voraussetzung für Komposition, keine optionale Nettigkeit.
Die Entscheidung des Benutzers (2026-11-22) ist, dass das Ergebnisschema die aktiven Felder sind — die Spalten, auf die die Elemente, Joins und Gruppen des Berichts verweisen —, genau die SELECT-Liste, die MADQueryActiveQueryFields bereits berechnet (MAD/Source/MADQueryActiveQueryFields.m:27-100). Keine Verhaltensänderung: describe gibt diese Liste als MADDataColumns zurück, ohne zu laufen. Die All-Spalten-Form bleibt ein Anliegen der Tabellenvorschau, kein Datenobjekt-Schema. Öffentliche Spaltennamen sollten benutzerseitig lesbar sein: MADDataColumn.caption existiert bereits für den Anzeigenamen, und der SELECT-Listen-Builder sollte ihn aus dem Anzeigenamen des Schemafelds setzen, wenn einer existiert, statt nur den internen Alias "Table0"."Field" offenzulegen.
Ein weiteres Stück Identität fehlt: die Wurzel. RptqDocument -mainQuery und RptqDatabase -defaultQuery sind beide hasQueries.anyObject (MAD/Source/rptq/RptqDocument+Extras.m:184-186, MAD/Source/rptq/RptqDatabase+Extras.m:88), und MADocument -database nimmt hasDatabaseSchemas.anyObject (MAD/Source/MADocument.m:1248-1258). Mit mehreren Datenobjekten in einem Dokument ist die Abfrage, die Betrachter und Designer rendern, nichtdeterministisch. Fügen Sie einen ausdrücklichen Wurzelverweis (oder ein Flag) zum Dokument hinzu und migrieren Sie die heutige einzige Abfrage dorthin. Builder-Entscheidung.
Heute kompiliert der Berichts-Refresh den Graphen zu SQL und ruft executeSQL:fieldKeys:onConnection:intoResultTable:withError: (MAD/Source/MADOperationRefresh.m:134). Das ist für einen SQL-Dialekt richtig. Für eine REST-API zwingt es den Treiber, SQL zurück in einen Graphen zu parsen, und die Teilmenge des Parsers passt an mindestens zwei Stellen nicht zum erzeugten SQL: der Generator hängt eine LIMIT-Klausel an (MADQueryFull.m:164), die MADSQLParser ablehnt (MAD/Source/sql/MADSQLParser.m:151-154), und der Designer kann NATURAL/CROSS-Joins erzeugen (RptqQueryLinks+Extras.m:76-86, MADQueryLinkType.h:15-16), die der Parser ebenfalls ablehnt (MADSQLParser.m:330-338). Den Parser wiederzuverwenden würde zudem die Schichtung umkehren: er lebt in MAD, über den Treibern, und unter Linux linkt mad die Treiber als Whole-Archive (Linux/CMakeLists.txt:469-474).
MADQuery/MADQueryFull direkt zu übergeben ist ebenso wenig die Antwort: MADQueryFull ist speichergebunden, in MAD, und berechnet die aktive Feldliste nur beim Bauen von SQL. Ein Treiber würde gegen den Dokumentspeicher kompilieren.
Fügen Sie ein treiberneutrales Wertobjekt in MADAPI hinzu:
@interface MADQueryPlanTable : NSObject
@property (copy) NSString *name; // schema table or object name
@property (copy) NSString *alias; // query alias
@property (copy, nullable) NSString *sourceIdentifier; // nil = schema table
@end
@interface MADQueryPlanField : NSObject
@property (strong) MADQueryPlanTable *table;
@property (copy) NSString *field;
@property (copy) NSString *outputKey; // exactly what the driver names the column
@end
@interface MADQueryPlanLink : NSObject
@property (assign) MADLinkType type; // moved down to MADAPI
@property (strong) MADQueryPlanTable *leftTable, *rightTable;
@property (copy) NSString *leftField, *rightField;
@end
@interface MADQueryPlanPredicate : NSObject
@property (assign) MADPredicateOperator op; // moved down to MADAPI
@property (strong) MADQueryPlanOperand *left, *right; // field reference or literal
@end
@interface MADQueryPlan : NSObject
@property (copy) NSArray<MADQueryPlanTable *> *tables;
@property (copy) NSArray<MADQueryPlanField *> *fields; // the active SELECT list
@property (copy) NSArray<MADQueryPlanLink *> *links;
@property (copy) NSArray<MADQueryPlanPredicate *> *predicates;
@property (copy) NSArray<MADQueryPlanSort *> *sort; // pushdown hint
@property (assign) NSUInteger limit;
@property (assign) NSUInteger offset;
@end
MADLinkType, MADPredicateOperator und MADSortOrder liegen derzeit in MAD (MAD/Source/MADQueryLinkType.h, MADPredicateOperator.h, MADSortOrder.h). Ein Plan in MADAPI kann sie nicht referenzieren, bis sie nach unten wandern (oder der Plan definiert seine eigenen Enums, was das Modell dupliziert). Die drei reinen Enums nach unten zu verschieben ist die richtige Behebung.
Die Ausführung wird eine optionale Methode am vorhandenen Protokoll:
@protocol MADDatabaseDataSource <NSObject>
// existing required methods stay ...
@optional
- (BOOL)executeQueryPlan:(MADQueryPlan *)plan
options:(MADDatabaseExecutionOptions *)options
intoResultTable:(id <MADDataTableWriting>)table
withError:(NSError **)error;
@end
@interface MADDatabaseExecutionOptions : NSObject
@property (copy) BOOL (^isCancelled)(void);
@property (copy) void (^progress)(double fraction, NSString *node);
@property (strong) id credentials; // driver-specific, or a resolver
@property (copy) NSArray<MADMaterializationReference *> *attachments; // SQLite composer
@end
Der Plan bleibt logisch; die Optionen tragen den Ausführungskontext. Ein komponierender SQLite-Treiber löst den sourceIdentifier jeder Tabelle auf eine in options gelieferte Anhängung (Pfad, Tabelle, Alias) auf. Das hält Dateipfade aus der Treiberoberfläche von Drittanbietern heraus und gibt Abbruch und Fortschritt pro Knoten ein Zuhause. Builder-Entscheidung.
MADOperationRefresh bevorzugt ihn, wenn der Treiber ihn implementiert, und fällt sonst auf den vorhandenen SQL-Pfad zurück. Die vier ausgelieferten Treiber brauchen am ersten Tag keine Änderung. Eine Referenzimplementierung kann den Plan intern zu SQL kompilieren und behaupten, dass er zur Ausgabe des aktuellen Compilers passt, was den Plan gegen die bestehende Suite festlegt.
Die Engine und die UI sollten einen Treiber fragen, was er kann, statt Treiber-IDs fest zu verdrahten:
@interface MADDatabaseCapabilities : NSObject
@property (assign) MADLinkTypeMask supportedLinkTypes;
@property (assign) MADPredicateOperatorMask supportedOperators;
@property (assign) BOOL supportsLimitOffset;
@property (assign) BOOL supportsServerSideSort;
@property (assign) BOOL supportsNativeStatementText; // SQL editor
@property (assign) BOOL isReadOnly;
@property (assign) NSUInteger maximumPageSize;
@end
Dies ersetzt die fest verdrahteten Treiberlisten und Join-Regeln in MADDesigner/Source/MADDriverSelectorController.m:64-90,124-140, MAD/Source/rptq/RptqDatabaseCredentals+MADDatabaseConnection.m:19-33, Mac/Source/MADMacConnectionWindowController.m:198-204,359-375, CLI/Source/MADCLIServe.m:277-291 und MADDesigner/Source/MADQueryAddLinkJoinTypeController.m:46-95. Die Registratur zählt die Treiber bereits auf (registeredDriverClasses); die UI kann sie plus driverName/imageIconName verwenden statt eines Switch.
getTables: / getTablesFromConnection:error: und fieldsForTable:connection:error:. Ein Nicht-SQL-Treiber gibt MADDatabaseTable- und MADDatabaseField-Werte zurück; der berichtende Benutzer sieht sie im Abfragedesigner genau wie heute Schematabellen.id <MADDataTableWriting>; der Treiber fügt MADDataColumns und Zeilen hinzu, verschlüsselt nach fieldKeys/outputKey.MADDatabaseDriver) bleiben. Der sauberere langfristige Vertrag legt Typ, Kennung, Fähigkeiten und Verbindungskonstruktion auf die Unterklasse MADDatabase; das kann neben dem aktuellen Protokoll hinzugefügt werden, ohne die vier Treiber zu brechen.Der „eine Treiber für eine ganze Klasse von Datenquellen“ des Benutzers ist ein Treiber, dessen Schema aus einem Quellmanifest kommt, nicht aus dem Code. Die Engine sieht ein gewöhnliches MADDatabase; das Manifest sagt dem Treiber, welche Tabellen, Felder, Endpunkte und Pagination-Regeln existieren.
Minimale Manifestform:
{
"name": "eBay Seller",
"baseURL": "https://api.ebay.com",
"resources": {
"listings": {
"path": "/sell/inventory/v1/inventory_item",
"rowsPath": "inventoryItems",
"primaryKey": "sku",
"pagination": { "limitParam": "limit", "offsetParam": "offset", "max": 100 },
"fields": {
"sku": "string",
"listingId": "string",
"product.title": "string",
"price.value": "number"
},
"filters": { "sku": { "eq": "sku" } }
}
}
}
Der Treiber bildet den Plan auf Anfragen ab:
tables[0] wählt die Ressource.fields werden eine Select-Liste oder ignoriert, wenn die API ganze Objekte zurückgibt.predicates werden Query-Parameter, wenn das Manifest eine Zuordnung nennt; andernfalls filtert der Treiber lokal.limit/offset treiben die Seitenschleife. Ohne Limit blättert der Treiber, bis erschöpft.links sind nativ, wenn die API sie unterstützt, clientseitig, wenn der Treiber einen Hash-Join implementiert, oder nicht unterstützt (die Fähigkeit deaktiviert den Link in der UI).MADDataType abgebildet.Verbindungsseitig deckt die heutige Zugangsdatenzeile die SQL-Treiber ab (host, username, password, database). Für einen API-Treiber, der ein Client-Secret, ein Refresh-Token, eine Marketplace-ID oder ein Sandbox-Flag braucht, ist die Entscheidung des Benutzers (2026-11-22) ein einzelnes erweiterbares Optionsfeld an den Zugangsdaten: eine Textspalte, die JSON (oder XML) hält, in das Speicherformat versioniert, vom Treiber geparst — statt einer neuen Speicherspalte pro Treiber. Die vorhandenen Felder bilden den häufigen Fall ab (host = Basis-URL, database = Manifestname, username = Client-ID, password = OAuth-Token). Sensible Werte (Client-Secret, Refresh-Token) gehören in den Schlüsselbund, nicht ins Dokument; das JSON hält die nicht-geheime Form plus einen Schlüsselbund-Verweis. Das ist kein Workaround — es ist der Erweiterungspunkt, damit ein Treiber das Dokumentformat nicht jedes Mal ändert, wenn er einen Parameter hinzufügt.
Die Urheberschaft des Manifests ist zuerst gebündelt/vom Entwickler erstellt (die Entscheidung des Benutzers, 2026-11-22): der Entwickler des Treibers schreibt das Manifest und liefert es mit dem Treiber aus. Ein benutzerseitiger Manifest-Editor/-Import und seine Vertrauensgrenze sind hinter dem Plugin-System zurückgestellt (§5.1). Der langfristige Wunsch — Treiber, die sich einstecken lassen und über die UI hinzugefügt/entfernt werden — ist hier festgehalten; es ist zuerst ein Anliegen für macOS/Linux/Windows und Server, weil iOS historisch das Laden beliebigen Drittanbietercodes blockiert hat, also bleiben Treiber unter iOS zur Buildzeit gelinkt.
Der generische Treiber trägt auch die Nicht-SQL-Verpflichtungen, die der Plan nicht hat: HTTP-Client und TLS, Auth-Auffrischung, Rate-Limits, Wiederholungen, Abbruch, Obergrenzen der Antwortgröße und Fehlerzuordnung. Diese gehören ins Treiberframework, nicht in die Engine.
Was der generische Treiber nicht kann, ist ebenso wichtig wie das, was er kann: beliebiges GraphQL, eine Quelle, deren Zeilen nicht tabellarisch sind, oder serverseitige Joins, die das Manifest nicht ausdrücken kann. Das Fähigkeitenobjekt ist, wie er das sagt, und der Abfragedesigner ist, wo der Benutzer es erfährt.
Das größere Ziel des Benutzers sind Treiber, die sich wie Plugins installieren, registrieren und abmelden und über die UI hinzugefügt oder entfernt werden können, statt in die App gelinkt zu sein. Die Registratur macht bereits prozessweise Registrierung per Link (§1 des Treiber-Tutorials); ein echtes Plugin-System ist eine Verpackungs- und Vertrauensfrage, die darauf geschichtet wird: dynamisches Laden, ein Entdeckungsort, Signierung/Sandboxing und eine UI. Das ist eine Funktion für macOS/Linux/Windows und Server, keine für iOS, und außerhalb des Umfangs der Phasen dieses Designs. Es ist hier vermerkt, damit sich die Treibernaht (Phase 0) nicht selbst in eine Ecke malt: die Typen für Plan, Fähigkeiten und Registrierung sollten aus einem dynamisch gelinkten Image ladbar bleiben, was keine Kompilierzeit-Kopplung an eine feste Treiberliste bedeutet.
Minimale Form, MAD_DATA_OBJECT.md §4.4 folgend:
RptqQuery erhält einen Namen. Es ist bereits die Definition.RptqQueryTable erhält eine zweite Art: ein Datenobjekt (Unterbericht) im selben Dokument, zusätzlich zu einer Schematabelle. Eine v1-Zeile, die eine Schematabelle nennt, bedeutet genau das, was sie heute bedeutet. Ein Verweis auf einen Bericht in einer anderen .mad-Datei ist über v1 hinaus aufgeschoben; wenn er kommt, braucht er eine Dokumentidentität und einen Pfad plus eine Live-/Pin-Markierung.fileURL.lastPathComponent.hash. Der Tabellenname bleibt t<tag>; das Tag wird die Identität des Objekts..mdcache) und seine Tabelle. Layout A behält eine Datei pro Objekt; Layout B würde das Dateimodell ändern.MADStoreSchema.m:314), also ist dies ein bekanntes Muster, kein neuer Mechanismus.Das .mad-Dokument bleibt eine Definition und enthält keine Daten, jetzt oder später — das ist die ausdrückliche Entscheidung des Benutzers. Snapshots und Materialisierungen sind begleitende Cache-Dateien auf dem System des Benutzers, und sie sind das, was ATTACH zusammensjoint. Die automatische Benennung dieser Cache-Dateien wandert vom Dateinamen-Hash zu einer stabilen Objektidentität, sodass Dateien nicht kollidieren.
.mad-Verweise sind eine spätere Ergänzung.MADOperationRefresh wird von der App, macOS und der CLI geteilt (CLI/Source/MADCLIDocument.m:120-127, Mac/Source/MADMacDocument.m:337-360), also gehört der topologische Durchlauf dorthin oder in einen Helfer, den er aufruft, nicht in jedes Frontend.So geordnet, dass jede Phase grün ausliefert und die Ein-Abfrage-App weiter funktioniert. Die erste Phase ist unabhängig von der Komposition und ist diejenige, die Nicht-SQL-Quellen freischaltet.
| Phase | Arbeit | Hängt ab von |
|---|---|---|
| 0 | Die Treibernaht. MADQueryPlan + Werttypen hinzufügen und die drei Enums nach MADAPI verschieben; das optionale executeQueryPlan: hinzufügen; Fähigkeiten hinzufügen; Refresh den Plan bevorzugen und auf SQL zurückfallen lassen. Den Plan in einem vorhandenen Treiber als Referenz implementieren und die Plan-zu-SQL-Äquivalenz mit Tests festlegen. Keine Verhaltensänderung. |
— |
| 1 | Der Datenobjekt-Vertrag. Die SELECT-Listen-Konstruktion von der Ausführung trennen; describe/execute hinzufügen; das Ergebnisschema als MADDataColumns zurückgeben; Refresh den Vertrag aufrufen lassen. Das ist MAD_DATA_OBJECT.md Phase 1. |
0 (überlappt) |
| 2 | Die Abfrage besitzt sich selbst. MADQueryFull verwendet die Abfrage, die es erhielt; dataTableForQuery: löst pro Abfrage auf; MADQueryActiveQueryFields beschränkt auf eine Abfrage; MADModelDocument spiegelt jede Abfrage. |
1 |
| 3 | Komposition im selben Dokument. Eine Abfragetabelle darf auf ein anderes Datenobjekt (Unterbericht) verweisen; topologischer Refresh; ATTACH-Unterstützung in MADDatabaseSqlite3; die komponierende Abfrage führt gegen den lokalen Cache aus. Das ist das Modell des Benutzers mit einer portablen Datei. |
1, 2 |
| 4 | Dateiübergreifende Komposition (aufgeschoben). Ein Verweis auf einen anderen .mad-Bericht; Dokumentidentität und Pfadauflösung; live vs. festgeschrieben; Dateikoordination; Zugangsdatenrichtlinie; Behandlung fehlender/umbenannter Dateien. Niedrigere Priorität: die Komposition im selben Dokument erfüllt das Modell des Benutzers. |
3 |
| 5 | Der generische API-Treiber. Ein manifestgesteuerter HTTP/JSON-Treiber; Schema aus dem Manifest; Plan-zu-Anfrage-Abbildung; Paginationsschleife; Typzuordnung; das erweiterbare Feld options der Zugangsdaten; eBay Seller als durchgearbeitetes Beispiel. |
0, 1 (und 3 für Joins) |
| 6 | Oberflächen und Dokumentation. Registraturgesteuerte Treiberlisten und Join-Regeln; Refresh-UI pro Knoten; CLI-Verben; das Tutorial zum Schreiben von Treibern aktualisiert um die Plan-/Fähigkeiten-Naht. | 0–5 |
Keine Phase: das Laden von Plug-and-Play-Treibern (§5.1) ist eine Funktion für macOS/Linux/Windows und Server, die getrennt von diesem Design verfolgt wird; nichts in den Phasen 0–6 hängt davon ab, und Phase 0 sollte lediglich eine Kopplung an eine feste Treiberliste vermeiden, damit dynamisches Laden möglich bleibt.
Phase 0 ist der Teil „nicht weit entfernt“: es sind neue Werttypen, eine optionale Methode, ein Zweig im Refresh und Tests. Es erfordert nicht, dass sich Speicher, UI oder Kompositionsmodell ändern. Phase 3 ist, wo das ATTACH-Modell des Benutzers landet, und sie ist kleiner, als sie klingt, weil SQLite bereits ein Treiber ist und der Compiler bereits einen Graphen sortiert.
Diese sind aus dem Code oder durch einen Design-Kompromiss geklärt; sie können überdacht werden, aber der Plan setzt sie voraus.
ATTACH. Eine .maddb pro Objekt; die komponierende Verbindung hängt sie an. Das folgt dem Ein-Tabelle-pro-Datei-Modell von MADDataTableFast. Layout B (mehrere Tabellen in einer Datei) ist ein späteres Refactoring, nicht v1. Dies ersetzt die Layout-B-Empfehlung von MAD_DATA_OBJECT.md §9.2 für dieses Design.MADDataColumns des Kindes und frischen Sie sie auf, wenn sich das Schema des Kindes ändert. Keine zweite Feldverweisart.hasQueries.anyObject.MADDatabaseExecutionOptions trägt Abbruch, Fortschritt, Zugangsdaten und die Anhängungsmenge des SQLite-Komponisten. MADQueryPlanTable.sourceIdentifier benennt die logische Quelle; er ist kein Dateipfad.SQLITE_MAX_ATTACHED anzuheben ist eine Buildänderung auf drei Plattformen, aufgeschoben.RptqQuery benennen; noch kein RptqDataObject einführen. MAD_DATA_OBJECT.md §9.1 empfiehlt dies, und es ist die kleinere Migration.MADDatabaseDriver aus Kompatibilitätsgründen an der Verbindungsklasse behalten. Ein Registrierungsvertrag auf Datenbankklassenebene kann später daneben hinzugefügt werden.Die Worte des Benutzers folgen; die Implikationen sind die des Autors.
MADQueryActiveQueryFields bereits berechnet (MADQueryActiveQueryFields.m:27-100). Der Benutzer: „es wären einfach die Felder, die in diesem Bericht verwendet werden.“ Die All-Spalten-Form ist nur ein Anliegen der Tabellenvorschau. Describe gibt dieselbe Liste als MADDataColumns zurück, ohne auszuführen. Zwei Konsequenzen sind als künftige Funktionen vermerkt, nicht als Teil dieser Arbeit: benutzerseitig lesbare Spaltennamen (MADDataColumn.caption setzen, das bereits existiert, statt nur den Alias "Table0"."Field" offenzulegen) und Vorschau-Paging (die Vorschau begrenzt derzeit auf ~512 Zeilen und sollte durch das vollständige Ergebnis blättern — der Benutzer hat dies für die Wunschliste markiert, also TODO.md des Benutzers, nicht dieses Dokument). Die Null-Zeilen-Regel gilt weiterhin: ein Quellobjekt materialisiert sein vollständiges Schema, selbst wenn es keine Zeilen zurückgibt..mad. Der Benutzer: „Die .mad-Datei beschreibt nur das Schema … das sollte sich nicht ändern … Es wäre in dem, was die Cache-Datei gerade ist … den Cache-Dateien, die Sqlite3-Datenspeicher sind, und das ist, was ATTACHed zusammengejoint würde.“ Das Archiv bleibt also definitionsonly; ein festgeschriebener Snapshot ist eine aufbewahrte .maddb/.mdcache, und die Benennung der Materialisierung wandert zu einer stabilen Objektidentität, um Kollisionen zu vermeiden..mad enthält mehrere Berichts-/Abfragedefinitionen; jede läuft zu einer SQLite-Tabelle; der komponierende Bericht ATTACHt sie. Das bewahrt die Ein-Datei-Eigenschaft und entfernt das iOS-Problem der dateiübergreifenden Neuauthorisierung für v1. Verweise auf andere Dokumente sind hinter der Komposition im selben Dokument zurückgestellt.MADQueryFull, die Ein-Slot-Datentabelle, die ungeteilten aktiven Felder) sind tragend für die heutige Ein-Abfrage-App. Sie müssen fallen, bevor eine zweite Abfrage — geschweige denn eine verschachtelte — ausführen kann.ATTACH hat ein Limit (SQLITE_MAX_ATTACHED, Standard 10) und braucht Alias-/Namensverwaltung und Pfad-Quoting. Entdecken Sie es nicht in der Produktion.MADAPI; die Typen für Plan und Fähigkeiten werden eine öffentliche Oberfläche. Versionieren Sie sie bewusst.docs/05-companion-files.md §5.1).docs/project/registers/TODO.md ist die eigene Wunschliste des Benutzers (der Wunsch nach Vorschau-Paging gehört dorthin), TASKS.md ist die Engineering-Warteschlange, und ROADMAP.md sagt, was als Nächstes aufgegriffen wird. Nichts hier wird auf Initiative eines Agenten begonnen.Zwei künftige Funktionen werden hier benannt, gehören aber in die Tracking-Dateien des Benutzers, nicht in dieses Design: die Behebung des Vorschau-Pagings (§9.2.1) und das Plug-and-Play-Treibersystem (§5.1). Dieses Dokument ist, wo ihre Form festgehalten wird; es plant sie nicht ein.
Der Abfrage-Arbeitsbereich baut die Funktion bereits. Die Refresh-Kette kompiliert und führt sie bereits aus. Die Ergebnistabelle ist bereits ein Schema und eine Ergebnismenge, auf der Platte als SQLite. SQLite ist bereits ein Treiber. Die Treiber geben bereits Tabellen zurück. Was fehlt, ist der Name, die Adresse, die Beschreibungshälfte und die strukturierte Abfrage, die ein Nicht-SQL-Treiber statt SQL-Text braucht. Diese sind additiv: ein Plan-Wertobjekt, ein Fähigkeitenobjekt, eine optionale Ausführungsmethode, eine stabile Objektidentität, eine zweite Art von Tabellenverweis, ein topologischer Durchlauf und ATTACH.
Die Komposition ist dann die bestehende Pipeline, adressiert durch etwas Besseres als einen Dateinamen-Hash. Der Nicht-SQL-Treiber ist dieselbe Pipeline mit einem anderen Ausführungskörper. Keines ist eine neue Engine; beide sind, was die Abstraktionen zu erlauben gebaut wurden.
Diese Seite ist eine deutsche Übersetzung des englischen Originals; bei Abweichungen ist der englische Originaltext maßgeblich.