{"record":{"id":"6dc647d4bf272da5","repo":"phalcon/cphalcon","slug":"the-index-tables-is-required-in-the-definition-a","errorCode":null,"errorMessage":"The index 'tables' is required in the definition array","messagePattern":"The index 'tables' is required in the definition array","errorType":"exception","errorClass":"MissingDefinitionKey","httpStatus":null,"severity":"error","filePath":"phalcon/Db/Dialect.zep","lineNumber":605,"sourceCode":"    /**\n     * Generate SQL to rollback a savepoint\n     */\n    public function rollbackSavepoint( string name) -> string\n    {\n        return \"ROLLBACK TO SAVEPOINT \" . name;\n    }\n\n    /**\n     * Builds a SELECT statement\n     */\n    public function select( array definition) -> string\n    {\n        var tables, columns, sql, distinct, joins, where, escapeChar, groupBy,\n            having, orderBy, limit, forUpdate, bindCounts;\n        array parts;\n\n        if unlikely !fetch tables, definition[\"tables\"] {\n            throw new MissingDefinitionKey(\"tables\");\n        }\n\n        if unlikely !fetch columns, definition[\"columns\"] {\n            throw new MissingDefinitionKey(\"columns\");\n        }\n\n        if fetch distinct, definition[\"distinct\"] {\n            if distinct {\n                let sql = \"SELECT DISTINCT\";\n            } else {\n                let sql = \"SELECT ALL\";\n            }\n        } else {\n            let sql = \"SELECT\";\n        }\n\n        fetch bindCounts, definition[\"bindCounts\"];\n        if typeof bindCounts !== \"array\" {","sourceCodeStart":587,"sourceCodeEnd":623,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Db/Dialect.zep#L587-L623","documentation":"Phalcon's SQL dialect base class throws MissingDefinitionKey (extends Phalcon\\Db\\Exception) from Dialect::select() when the definition array passed to the SELECT compiler has no 'tables' key. The dialect cannot build a SELECT without knowing which tables to read, so it fails fast before generating SQL. The same key is required by every dialect (Mysql, Postgresql, Sqlite) since they all inherit this method.","triggerScenarios":"Calling $dialect->select(['columns' => ...]) or $adapter->getDialect()->select($definition) with a definition array that omits 'tables'. Also hitting it indirectly when code builds a definition array dynamically and a branch never sets $definition['tables'], or when the key is misspelled ('table', 'fromTable').","commonSituations":"Hand-assembled definition arrays from query metadata or request input; refactoring a Query Builder pipeline where 'tables' was set on a different array branch; migrating code from an older Phalcon version that silently tolerated partial definitions.","solutions":["Add a non-empty 'tables' entry to the definition array, e.g. definition['tables'] = ['robots'] or a qualified expression array","If the array is built dynamically, assert isset($definition['tables']) before calling select() and fail with your own descriptive error","Check for misspellings or accidental overwriting of the key ('table', 'tableName') right before the call","Prefer Phalcon\\Db\\QueryBuilder or PHQL, which always emits the 'tables' key for you"],"exampleFix":"// before\n$sql = $dialect->select([\n    'columns' => ['id', 'name'],\n]);\n\n// after\n$sql = $dialect->select([\n    'tables'  => ['robots'],\n    'columns' => ['id', 'name'],\n]);","handlingStrategy":"validation","validationCode":"if (!isset($definition['tables']) || $definition['tables'] === []) {\n    throw new InvalidArgumentException('SELECT definition requires a non-empty \"tables\" entry');\n}","typeGuard":null,"tryCatchPattern":"try {\n    $sql = $dialect->select($definition);\n} catch (\\Phalcon\\Db\\Exceptions\\MissingDefinitionKey $e) {\n    // $e->getMessage() names the missing key, e.g. \"The index 'tables' is required...\"\n    throw new InvalidArgumentException('Bad select definition: ' . $e->getMessage(), 0, $e);\n}","preventionTips":["Centralize definition-array construction in one factory that always sets 'tables' and 'columns'","Prefer Phalcon\\Db\\QueryBuilder over hand-built definition arrays","Add unit tests asserting the required keys exist before calling select()"],"tags":["phalcon","sql","dialect","select","definition-array"],"backgroundTag":"missing-definition-key","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}