{"record":{"id":"bfe1a827e5eb5c84","repo":"phalcon/cphalcon","slug":"the-index-columns-is-required-in-the-definition","errorCode":null,"errorMessage":"The index 'columns' is required in the definition array","messagePattern":"The index 'columns' is required in the definition array","errorType":"exception","errorClass":"MissingDefinitionKey","httpStatus":null,"severity":"error","filePath":"phalcon/Db/Dialect.zep","lineNumber":609,"sourceCode":"    {\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\" {\n            let bindCounts = [];\n        }\n\n        let escapeChar = this->escapeChar;","sourceCodeStart":591,"sourceCodeEnd":627,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Db/Dialect.zep#L591-L627","documentation":"Dialect::select() throws MissingDefinitionKey (extends Phalcon\\Db\\Exception) when the definition array lacks the 'columns' key. Even for SELECT * the compiler requires an explicit columns entry (e.g. a scalar expression wrapping '*'); it will not guess a default projection. It fails immediately at the top of select(), after the 'tables' check.","triggerScenarios":"Calling $dialect->select(['tables' => ['robots']]) without a 'columns' key. Also passing columns under a wrong key ('fields', 'select'), or unsetting definition['columns'] in a conditional before the call.","commonSituations":"Building a generic query layer where columns are optional in the calling API; partial definition arrays assembled from multiple sources; code copied from SELECT examples that omitted the projection.","solutions":["Add a 'columns' entry; for all columns use a scalar expression: definition['columns'] = [['type' => 'scalar', 'value' => '*']] or a list of column names","Default the key in your builder code before calling select(): $definition['columns'] ??= [['type' => 'scalar', 'value' => '*']]","Verify no branch of your definition-building code drops or renames 'columns'","Use Phalcon\\Db\\QueryBuilder, which normalizes columns for you"],"exampleFix":"// before\n$sql = $dialect->select(['tables' => ['robots']]);\n\n// after\n$sql = $dialect->select([\n    'tables'  => ['robots'],\n    'columns' => [['type' => 'scalar', 'value' => '*']],\n]);","handlingStrategy":"validation","validationCode":"$definition['columns'] = $definition['columns'] ?? [['type' => 'scalar', 'value' => '*']];\nif (!is_array($definition['columns'])) {\n    throw new InvalidArgumentException('\"columns\" must be an array of expressions');\n}","typeGuard":null,"tryCatchPattern":"try {\n    $sql = $dialect->select($definition);\n} catch (\\Phalcon\\Db\\Exceptions\\MissingDefinitionKey $e) {\n    throw new InvalidArgumentException('Bad select definition: ' . $e->getMessage(), 0, $e);\n}","preventionTips":["Default 'columns' to a '*' scalar expression in your query builder","Never unset or rename 'columns' when post-processing definitions","Use Query Builder so projection handling is done for you"],"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"}