tinybird 0.0.1.dev17__py3-none-any.whl → 0.0.1.dev18__py3-none-any.whl

tinybird/tb/modules/datafile/common.py

@@ -33,13 +33,42 @@ class DatafileSyntaxError(Exception):
     def __init__(self, message: str, lineno: int, pos: int, hint: Optional[str] = None):
         super().__init__(message)
         self.message = message
+        self.context = None
         self.hint = hint
         self.lineno = lineno
         self.pos = pos
 
+    def add_context(self, context: str):
+        self.context = context
+
+    def get_context_from_file_contents(self, s: str) -> None:
+        lines = s.splitlines()
+
+        start_line = max(0, self.lineno - 3)  # 2 lines before
+        end_line = self.lineno  # Only context before the error
+
+        # Calculate padding needed for line numbers
+        max_line_digits = len(str(end_line))
+
+        context = []
+        for i in range(start_line, end_line):
+            line_num = str(i + 1).rjust(max_line_digits)
+            line = lines[i].rstrip()
+            context.append(f"{line_num}: {line}")
+
+            # Add pointer line if this is the error line
+            if i + 1 == self.lineno:
+                pointer = " " * (max_line_digits + 2 + self.pos - 1) + "^"
+                context.append(pointer)
+
+        error_context = "\n".join(context)
+        self.add_context(error_context)
+
     def __str__(self) -> str:
-        hint = f" {self.hint}." if self.hint else ""
-        return f"{self.message} at {self.lineno}:{self.pos}." + hint
+        output = f"{self.message}"
+        output += f"\n\n{self.context}" if self.context else f" at {self.lineno}:{self.pos}."
+        output += f"\n{self.hint}." if self.hint else ""
+        return output
 
 
 class SchemaSyntaxError(DatafileSyntaxError):
@@ -242,15 +271,21 @@ def parse_indexes_structure(indexes: Optional[List[str]]) -> List[TableIndex]:
     >>> parse_indexes_structure(["index_name u64 * length(s)"])
     Traceback (most recent call last):
     ...
-    tinybird.tb.modules.datafile.common.IndexesSyntaxError: Invalid INDEX syntax at 1:1. Usage: `[INDEX] name expr TYPE type_full GRANULARITY granularity`.
+    tinybird.tb.modules.datafile.common.IndexesSyntaxError: Invalid INDEX syntax at 1:1.
+    Usage: `[INDEX] name expr TYPE type_full GRANULARITY granularity`.
+
     >>> parse_indexes_structure(["index_name a TYPE set(100) GRANULARITY 100, index_name_bf mapValues(d) TYPE bloom_filter(0.001) GRANULARITY 16"])
     Traceback (most recent call last):
     ...
-    tinybird.tb.modules.datafile.common.IndexesSyntaxError: Invalid INDEX syntax at 1:1. Usage: `[INDEX] name expr TYPE type_full GRANULARITY granularity`.
+    tinybird.tb.modules.datafile.common.IndexesSyntaxError: Invalid INDEX syntax at 1:1.
+    Usage: `[INDEX] name expr TYPE type_full GRANULARITY granularity`.
+
     >>> parse_indexes_structure(["", "    ", "     wrong_index_syntax,"])
     Traceback (most recent call last):
     ...
-    tinybird.tb.modules.datafile.common.IndexesSyntaxError: Invalid INDEX syntax at 3:6. Usage: `[INDEX] name expr TYPE type_full GRANULARITY granularity`.
+    tinybird.tb.modules.datafile.common.IndexesSyntaxError: Invalid INDEX syntax at 3:6.
+    Usage: `[INDEX] name expr TYPE type_full GRANULARITY granularity`.
+
     >>> parse_indexes_structure(["my_index m['key'] TYPE ngrambf_v1(1, 1024, 1, 42) GRANULARITY 1"])
     [TableIndex(name='my_index', expr="m['key']", type_full='ngrambf_v1(1, 1024, 1, 42)', granularity='1')]
     >>> parse_indexes_structure(["my_index_lambda arrayMap(x -> tupleElement(x,'message'), column_name) TYPE ngrambf_v1(1, 1024, 1, 42) GRANULARITY 1"])
@@ -513,9 +548,9 @@ def _parse_table_structure(schema: str) -> List[Dict[str, Any]]:
                 if c not in valid_chars_name:
                     raise SchemaSyntaxError(
                         message=f"Column name contains invalid character {repr(c)}",
-                        hint="Tip: use backticks",
+                        hint="Hint: use backticks",
                         lineno=line,
-                        pos=i + 1,
+                        pos=pos,
                     )
                 advance_single_char()
             return schema[begin:i]
@@ -524,7 +559,11 @@ def _parse_table_structure(schema: str) -> List[Dict[str, Any]]:
             advance_single_char()
             return get_backticked()
 
-    def parse_expr(lookup: Iterable[SyntaxExpr]) -> str:
+    def parse_expr(lookup: Iterable[SyntaxExpr], attribute: str) -> str:
+        """Parse an expression for an attribute.
+
+        The name of the attribute is used to generate the error message.
+        """
         nonlocal i, line, pos
 
         begin: int = i
@@ -542,13 +581,38 @@ def _parse_table_structure(schema: str) -> List[Dict[str, Any]]:
             elif c == "(" and (context is None or context == "("):
                 context_stack.append("(")
             elif context is None and lookahead_matches(lookup):
+                if i == begin:
+                    # This happens when we're parsing a column and an expr is missing for an attribute that requires it,
+                    # like DEFAULT or CODEC. For example:
+                    # SCHEMA >
+                    #     timestamp DateTime DEFAULT,
+                    #     col_b Int32
+                    raise SchemaSyntaxError(
+                        message=f"Missing mandatory value for {attribute}",
+                        lineno=line,
+                        pos=pos,
+                    )
                 return schema[begin:i].strip(" \t\r\n")
             elif (context is None and c not in valid_chars_fn) or (context == "(" and c not in valid_chars_fn):
                 raise SchemaSyntaxError(message=f"Invalid character {repr(c)}", lineno=line, pos=pos)
             advance_single_char()
+
+        # Check for unclosed contexts before returning
+        if len(context_stack) > 1:
+            last_context = context_stack[-1]
+            closing_char = "'" if last_context == "'" else ('"' if last_context == '"' else ")")
+            raise SchemaSyntaxError(message=f"Expected closing {closing_char}", lineno=line, pos=pos)
+
         if i == begin:
-            # TODO(eclbg): Turn this into a SchemaSyntaxError. I don't know when it happens
-            raise ValueError(format_parse_error(schema, i, pos, "wrong value", line=line))
+            # This happens when we're parsing a column and an expr is missing for an attribute that requires it, like
+            # DEFAULT or CODEC, and we reach the end of the schema. For example:
+            # SCHEMA >
+            #     timestamp DateTime DEFAULT
+            raise SchemaSyntaxError(
+                message=f"Missing mandatory value for {attribute}",
+                lineno=line,
+                pos=pos,
+            )
         return schema[begin:].strip(" \t\r\n")
 
     columns: List[Dict[str, Any]] = []
@@ -556,7 +620,6 @@ def _parse_table_structure(schema: str) -> List[Dict[str, Any]]:
     name: str = ""
     _type: str = ""
     default: str = ""
-    materialized: str = ""
     codec: str = ""
     jsonpath: str = ""
     last: Optional[SyntaxExpr] = None
@@ -564,24 +627,22 @@ def _parse_table_structure(schema: str) -> List[Dict[str, Any]]:
     col_end: Tuple[int, int] = (0, 0)  # (0, 0) means not set. It's not a valid line/pos as they start at 1
 
     def add_column(found: str) -> None:
-        nonlocal name, _type, default, materialized, codec, jsonpath, col_start, col_end
-        if not name:
-            # TODO(eclbg): get rid of this ValueError and replace it with a custom one so it can be handled by the
-            # caller
-            raise ValueError(
-                format_parse_error(schema, i, pos, f"Syntax error: expecting NAME, found {found}", line=line)
-            )
+        nonlocal name, _type, default, codec, jsonpath, col_start, col_end
+        lineno, pos = col_start
         default = "" if not default else f"DEFAULT {default}"
-        materialized = "" if not materialized else f"MATERIALIZED {materialized}"
         codec = "" if not codec else f"CODEC{codec}"
-        # TODO(eclbg): We should validate the column as a whole. Name is mandatory, and one of type, default_value or
-        # materialized (I think).
+        if not name or not (_type or default):
+            raise SchemaSyntaxError(
+                message="Column name and either type or DEFAULT are required",
+                lineno=lineno,
+                pos=pos,
+            )
         columns.append(
             {
                 "name": name,
                 "type": _type,
                 "codec": codec,
-                "default_value": default or materialized,
+                "default_value": default,
                 "jsonpath": jsonpath,
                 # "col_start": col_start,
                 # "col_end": col_end,
@@ -590,7 +651,6 @@ def _parse_table_structure(schema: str) -> List[Dict[str, Any]]:
         name = ""
         _type = ""
         default = ""
-        materialized = ""
         codec = ""
         jsonpath = ""
 
@@ -619,7 +679,9 @@ def _parse_table_structure(schema: str) -> List[Dict[str, Any]]:
             advance("")
             valid_next = [NULL, NOTNULL, DEFAULT, MATERIALIZED, ALIAS, CODEC, TTL, JSONPATH, COMMA, NEW_LINE]
             type_start_pos = pos  # Save the position of the type start to use it in the error message
-            detected_type = parse_expr([NULL, NOTNULL, DEFAULT, MATERIALIZED, ALIAS, CODEC, TTL, JSONPATH, COMMA])
+            detected_type = parse_expr(
+                [NULL, NOTNULL, DEFAULT, MATERIALIZED, ALIAS, CODEC, TTL, JSONPATH, COMMA], "TYPE"
+            )
             try:
                 # Imported in the body to be compatible with the CLI
                 from chtoolset.query import check_compatible_types
@@ -633,7 +695,9 @@ def _parse_table_structure(schema: str) -> List[Dict[str, Any]]:
                 ):
                     raise SchemaSyntaxError(message=str(e), lineno=line, pos=type_start_pos)
                 else:
-                    raise e
+                    # TODO(eclbg): The resulting error message is a bit confusing, as the clickhouse error contains some
+                    # references to positions that don't match the position in the schema.
+                    raise SchemaSyntaxError(f"Error parsing type: {e}", lineno=line, pos=type_start_pos)
             except ModuleNotFoundError:
                 pass
             _type = detected_type
@@ -658,14 +722,16 @@ def _parse_table_structure(schema: str) -> List[Dict[str, Any]]:
             advance("DEFAULT")
             valid_next = [
                 CODEC,
-                TTL,
                 COMMA,
-                # The three matches below are never valid. We're adding them here to avoid just complaining about their placement.
+                JSONPATH,
+                # The matches below are not supported. We're adding them here to say they aren't, instead of just
+                # complaining about their placement.
                 MATERIALIZED,
+                TTL,
                 NULL,
                 NOTNULL,
             ]
-            default = parse_expr([NOTNULL, DEFAULT, MATERIALIZED, ALIAS, CODEC, TTL, JSONPATH, COMMA])
+            default = parse_expr([NOTNULL, DEFAULT, MATERIALIZED, ALIAS, CODEC, TTL, JSONPATH, COMMA], "DEFAULT")
         elif found == MATERIALIZED:
             advance("")
             raise SchemaSyntaxError(
@@ -684,15 +750,16 @@ def _parse_table_structure(schema: str) -> List[Dict[str, Any]]:
         elif found == CODEC:
             advance("CODEC")
             valid_next = [
-                TTL,
                 COMMA,
                 JSONPATH,
-                # The three matches below are never valid. We're adding them here to avoid just complaining about their placement.
+                # The matches below are not supported. We're adding them here to say they aren't, instead of just
+                # complaining about their placement.
                 MATERIALIZED,
+                TTL,
                 NULL,
                 NOTNULL,
             ]
-            codec = parse_expr([NOTNULL, DEFAULT, MATERIALIZED, ALIAS, CODEC, TTL, JSONPATH, COMMA])
+            codec = parse_expr([NOTNULL, DEFAULT, MATERIALIZED, ALIAS, CODEC, TTL, JSONPATH, COMMA], "CODEC")
         elif found == TTL:
             advance("")  # We need to advance to get the correct position
             # Not implemented
@@ -706,22 +773,20 @@ def _parse_table_structure(schema: str) -> List[Dict[str, Any]]:
             advance("`json:")
             jsonpath = get_backticked()
         elif found == COMMA:
-            if name == "INDEX":
-                advance(",")
-                continue
             advance(",")
             valid_next = []
             col_end = (line, pos)
             add_column("COMMA")
-        elif found == NEW_LINE or (name == "INDEX" and not found):
+        elif found == NEW_LINE:
             i += 1
         else:
+            # Note(eclbg): I haven't found any case where this error is raised.
             raise ValueError(
                 format_parse_error(
                     schema,
                     i,
                     pos,
-                    "wrong value, DEFAULT, MATERIALIZED, CODEC, TTL expressions, a column data type, a comma, a new line or a jsonpath",
+                    "wrong value. Expected a data type, DEFAULT, CODEC, a jsonpath, a comma, or a new line",
                     line=line,
                 )
             )
@@ -819,217 +884,128 @@ def schema_to_sql_columns(schema: List[Dict[str, Any]]) -> List[str]:
 
 
 def parse_table_structure(schema: str) -> List[Dict[str, Any]]:
-    """This parses the SQL schema for a CREATE TABLE
-    Columns follow the syntax: name1 [type1] [DEFAULT expr1] [CODEC compression_codec] [TTL expr1] [JSONPATH `json:jsonpath`] [,]
-
-    The ClickHouse reference is followed pretty loosely at this point.
-    Reference: https://clickhouse.tech/docs/en/sql-reference/statements/create/table/#syntax-forms
-
-    >>> parse_table_structure('potato') # doctest: +SKIP
-    Traceback (most recent call last):
-    ...
-    tinybird.sql.MalformedColumnError: Column name and either type or default_value are required
-
-    >>> parse_table_structure('    potato Int32')
-    [{'name': 'potato', 'type': 'Int32', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'potato'}]
-
-    >>> parse_table_structure('`c Int32')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: Expected closing backtick at 1:3.
-
-    >>> parse_table_structure('c Float32, b String')
-    [{'name': 'c', 'type': 'Float32', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'c'}, {'name': 'b', 'type': 'String', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'b'}]
-
-    >>> parse_table_structure('c Float32,--comment\\nb String')
-    [{'name': 'c', 'type': 'Float32', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'c'}, {'name': 'b', 'type': 'String', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'b'}]
-
-    >>> parse_table_structure('c Float32,--comment\\nb String --another-comment')
-    [{'name': 'c', 'type': 'Float32', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'c'}, {'name': 'b', 'type': 'String', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'b'}]
-
-    >>> parse_table_structure('c Float32 --first-comment\\n,--comment\\nb String --another-comment')
-    [{'name': 'c', 'type': 'Float32', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'c'}, {'name': 'b', 'type': 'String', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'b'}]
-
-    >>> parse_table_structure('--random comment here\\nc Float32 --another comment\\n,--another one\\nb String --this is the last one')
-    [{'name': 'c', 'type': 'Float32', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'c'}, {'name': 'b', 'type': 'String', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'b'}]
-
-    >>> parse_table_structure('--extra comment\\nc--extra comment\\nFloat32--extra comment\\n,--extra comment\\nb--extra comment\\nString--extra comment')
-    [{'name': 'c', 'type': 'Float32', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'c'}, {'name': 'b', 'type': 'String', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'b'}]
-
-    >>> parse_table_structure('c Nullable(Float32)')
-    [{'name': 'c', 'type': 'Float32', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': True, 'normalized_name': 'c'}]
-
-    >>> parse_table_structure('c Nullable(Float32) DEFAULT NULL')
-    [{'name': 'c', 'type': 'Float32', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': True, 'normalized_name': 'c'}]
-
-    >>> parse_table_structure("c String DEFAULT 'bla'")
-    [{'name': 'c', 'type': 'String', 'codec': None, 'default_value': "DEFAULT 'bla'", 'jsonpath': None, 'nullable': False, 'normalized_name': 'c'}]
-
-    >>> parse_table_structure('`foo.bar` UInt64')
-    [{'name': 'foo.bar', 'type': 'UInt64', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'foo.bar'}]
-
-    >>> parse_table_structure('double_value Float64 CODEC(LZ4HC(2))')
-    [{'name': 'double_value', 'type': 'Float64', 'codec': 'CODEC(LZ4HC(2))', 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'double_value'}]
-
-    >>> parse_table_structure('doubl/e_value Float64 CODEC(LZ4HC(2))')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: Column name contains invalid character '/' at 1:6. Tip: use backticks.
-
-    >>> parse_table_structure('`c` Nullable(Float32)')
-    [{'name': 'c', 'type': 'Float32', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': True, 'normalized_name': 'c'}]
-
-    >>> parse_table_structure('wadus INT UNSIGNED')
-    [{'name': 'wadus', 'type': 'INT UNSIGNED', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'wadus'}]
-
-    >>> parse_table_structure('c Int32 CODEC(Delta, LZ4)\\n')
-    [{'name': 'c', 'type': 'Int32', 'codec': 'CODEC(Delta, LZ4)', 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'c'}]
-
-    >>> parse_table_structure('c  SimpleAggregateFunction(sum, Int32),\\np SimpleAggregateFunction(sum, Int32)')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: Incompatible data types between aggregate function 'sum' which returns Int64 and column storage type Int32 at 1:4.
-
-    >>> parse_table_structure('c Int32 CODEC(Delta, LZ4) Materialized b*2\\n')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 1:27.
-
-    >>> parse_table_structure('c Int32 CODEC(Delta, LZ4) Materialized ifNull(b*2, 0)\\n')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 1:27.
-
-    >>> parse_table_structure('c Int32 Materialized b*2\\n')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 1:9.
-
-    >>> parse_table_structure('c Int32 Materialized b != 1 ? b*2: pow(b, 3)\\n')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 1:9.
-
-    >>> parse_table_structure('')
-    []
-
-    >>> parse_table_structure('`date` Date,`timezone` String,`offset` Int32')
-    [{'name': 'date', 'type': 'Date', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'date'}, {'name': 'timezone', 'type': 'String', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'timezone'}, {'name': 'offset', 'type': 'Int32', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'offset'}]
-
-    >>> parse_table_structure('c Int32 Materialized b*2 CODEC(Delta, LZ4)\\n')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 1:9.
-
-    >>> parse_table_structure('c Int32 Materialized ifNull(b*2, 0) CODEC(Delta, LZ4)\\n')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 1:9.
-
-    >>> parse_table_structure('`temperature_delta` Float32 MATERIALIZED temperature CODEC(Delta(4), LZ4)')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 1:29.
-
-    >>> parse_table_structure('foo^bar Float32')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: Column name contains invalid character '^' at 1:4. Tip: use backticks.
-
-    >>> parse_table_structure('foo Float#32')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: Invalid character '#' at 1:10.
-
-    >>> parse_table_structure('foo Float32 DEFAULT 13, bar UInt64')
-    [{'name': 'foo', 'type': 'Float32', 'codec': None, 'default_value': 'DEFAULT 13', 'jsonpath': None, 'nullable': False, 'normalized_name': 'foo'}, {'name': 'bar', 'type': 'UInt64', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'bar'}]
-
-    >>> parse_table_structure('foo Float32 DEFAULT 1$$$3')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: Invalid character '$' at 1:22.
-
-    >>> parse_table_structure('foo Float32 CODEC(Delta(4), LZ#4)')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: Invalid character '#' at 1:31.
-
-    >>> parse_table_structure('\\n    `temperature` Float32,\\n    `temperature_delta` Float32 MATERIALIZED temperature CODEC(Delta(4), LZ4)\\n    ')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 3:33.
-
-    >>> parse_table_structure('temperature Float32, temperature_delta Float32 MATERIALIZED temperature Codec(Delta(4)), temperature_doubledelta Float32 MATERIALIZED temperature Codec(DoubleDelta), temperature_doubledelta_lz4 Float32 MATERIALIZED temperature Codec(DoubleDelta, LZ4)')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 1:48.
-
-    >>> parse_table_structure('t UInt8  CODEC(Delta(1), LZ4)')
-    [{'name': 't', 'type': 'UInt8', 'codec': 'CODEC(Delta(1), LZ4)', 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 't'}]
-
-    >>> parse_table_structure('tt UInt8  MATERIALIZED t')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 1:11.
-
-    >>> parse_table_structure('tt UInt8  MATERIALIZED t  CODEC(Delta(1), LZ4)')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 1:11.
-
-    >>> parse_table_structure('tt SimpleAggregateFunction(any, Nullable(UInt8))')
-    [{'name': 'tt', 'type': 'SimpleAggregateFunction(any, Nullable(UInt8))', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'tt'}]
-
-    >>> parse_table_structure("timestamp DateTime MATERIALIZED toDateTime(JSONExtractInt(JSONExtractRaw(record, 'payload'), 'timestamp') / 1000)")
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 1:20.
-
-    >>> parse_table_structure("`test_default_cast` DEFAULT plus(13,1)")
-    [{'name': 'test_default_cast', 'type': '', 'codec': None, 'default_value': 'DEFAULT plus(13,1)', 'jsonpath': None, 'nullable': False, 'normalized_name': 'test_default_cast'}]
-
-    >>> parse_table_structure("hola Int, `materialized` String MATERIALIZED upper(no_nullable_string)")
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 1:33.
-
-    >>> parse_table_structure('`a2` String `json:$.a2`, `a3` String `json:$.a3`\\n')
-    [{'name': 'a2', 'type': 'String', 'codec': None, 'default_value': None, 'jsonpath': '$.a2', 'nullable': False, 'normalized_name': 'a2'}, {'name': 'a3', 'type': 'String', 'codec': None, 'default_value': None, 'jsonpath': '$.a3', 'nullable': False, 'normalized_name': 'a3'}]
-
-    >>> parse_table_structure("`arr` Array(String) DEFAULT ['-']")
-    [{'name': 'arr', 'type': 'Array(String)', 'codec': None, 'default_value': "DEFAULT ['-']", 'jsonpath': None, 'nullable': False, 'normalized_name': 'arr'}]
-
-    >>> parse_table_structure("`arr` Array(String) DEFAULT array('-')")
-    [{'name': 'arr', 'type': 'Array(String)', 'codec': None, 'default_value': "DEFAULT array('-')", 'jsonpath': None, 'nullable': False, 'normalized_name': 'arr'}]
-
-    >>> parse_table_structure('`a2` Float32 CODEC(Delta, ZSTD(4)) `json:$.a2`, `a3` String `json:$.a3`\\n')
-    [{'name': 'a2', 'type': 'Float32', 'codec': 'CODEC(Delta, ZSTD(4))', 'default_value': None, 'jsonpath': '$.a2', 'nullable': False, 'normalized_name': 'a2'}, {'name': 'a3', 'type': 'String', 'codec': None, 'default_value': None, 'jsonpath': '$.a3', 'nullable': False, 'normalized_name': 'a3'}]
-
-    >>> parse_table_structure('`a` String, INDEX index_name a TYPE set(100) GRANULARITY 100')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: Forbidden INDEX definition at 1:13. Indexes are not allowed in SCHEMA section. Use the INDEXES section instead.
-
-    >>> parse_table_structure('    `a` String,\\n    INDEX index_name a TYPE set(100, 1) GRANULARITY 100')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: Forbidden INDEX definition at 2:5. Indexes are not allowed in SCHEMA section. Use the INDEXES section instead.
-
-    >>> parse_table_structure('`index` String, INDEX index_name a TYPE set(100, 1) GRANULARITY 100')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: Forbidden INDEX definition at 1:17. Indexes are not allowed in SCHEMA section. Use the INDEXES section instead.
-
-    >>> parse_table_structure('`a2` String `json:$.a--2`, `a3` String `json:$.a3`\\n')
-    [{'name': 'a2', 'type': 'String', 'codec': None, 'default_value': None, 'jsonpath': '$.a--2', 'nullable': False, 'normalized_name': 'a2'}, {'name': 'a3', 'type': 'String', 'codec': None, 'default_value': None, 'jsonpath': '$.a3', 'nullable': False, 'normalized_name': 'a3'}]
-
-    >>> parse_table_structure('a InvalidType')
-    Traceback (most recent call last):
-    ...
-    tinybird.tb.modules.datafile.common.SchemaSyntaxError: Unknown data type family: InvalidType at 1:3.
-
-    >>> parse_table_structure('a Int32 DEFAULT 'a') # doctest: +SKIP
-    # should fail as the type and default expr are incompatible
+    """Parse a table schema definition into a structured format.
+    Columns follow the syntax: name [type] [DEFAULT expr] [CODEC codec] [JSONPATH `json:jsonpath`] [,]
+
+    Args:
+        schema: The schema definition string
+
+    Returns:
+        List of dictionaries containing column definitions
+
+    Examples:
+        >>> parse_table_structure('')  # Empty schema
+        []
+
+        >>> parse_table_structure('col Int32')  # Basic column
+        [{'name': 'col', 'type': 'Int32', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'col'}]
+
+        >>> parse_table_structure('col1 Int32, col2 String')  # Multiple columns
+        [{'name': 'col1', 'type': 'Int32', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'col1'}, {'name': 'col2', 'type': 'String', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'col2'}]
+
+        >>> parse_table_structure('col Int32 DEFAULT 0')  # With DEFAULT
+        [{'name': 'col', 'type': 'Int32', 'codec': None, 'default_value': 'DEFAULT 0', 'jsonpath': None, 'nullable': False, 'normalized_name': 'col'}]
+
+        >>> parse_table_structure('col DEFAULT 42')  # Column without type but with default
+        [{'name': 'col', 'type': '', 'codec': None, 'default_value': 'DEFAULT 42', 'jsonpath': None, 'nullable': False, 'normalized_name': 'col'}]
+
+        >>> parse_table_structure('col String CODEC(ZSTD)')  # With CODEC
+        [{'name': 'col', 'type': 'String', 'codec': 'CODEC(ZSTD)', 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'col'}]
+
+        >>> parse_table_structure('`column.name!@#$%` String')  # Quoted identifier
+        [{'name': 'column.name!@#$%', 'type': 'String', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'column.name!@#$%'}]
+
+        >>> parse_table_structure('col Nullable(Int32)')  # Nullable type
+        [{'name': 'col', 'type': 'Int32', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': True, 'normalized_name': 'col'}]
+
+        >>> parse_table_structure('col Array(Int32)')  # Complex type
+        [{'name': 'col', 'type': 'Array(Int32)', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'col'}]
+
+        >>> parse_table_structure('col SimpleAggregateFunction(any, Int32)')  # Aggregate function
+        [{'name': 'col', 'type': 'SimpleAggregateFunction(any, Int32)', 'codec': None, 'default_value': None, 'jsonpath': None, 'nullable': False, 'normalized_name': 'col'}]
+
+    Error cases:
+        >>> parse_table_structure('col')  # Missing type
+        Traceback (most recent call last):
+        ...
+        tinybird.tb.modules.datafile.common.SchemaSyntaxError: Column name and either type or DEFAULT are required at 1:1.
+
+        >>> parse_table_structure('`col Int32')  # Unclosed backtick
+        Traceback (most recent call last):
+        ...
+        tinybird.tb.modules.datafile.common.SchemaSyntaxError: Expected closing backtick at 1:5.
+
+        >>> parse_table_structure('col Int32 DEFAULT')  # Missing DEFAULT value
+        Traceback (most recent call last):
+        ...
+        tinybird.tb.modules.datafile.common.SchemaSyntaxError: Missing mandatory value for DEFAULT at 1:18.
+
+        >>> parse_table_structure('col Int32 CODEC')  # Missing CODEC parameters
+        Traceback (most recent call last):
+        ...
+        tinybird.tb.modules.datafile.common.SchemaSyntaxError: Missing mandatory value for CODEC at 1:16.
+
+        >>> parse_table_structure('col#name Int32')  # Invalid character in name
+        Traceback (most recent call last):
+        ...
+        tinybird.tb.modules.datafile.common.SchemaSyntaxError: Column name contains invalid character '#' at 1:4.
+        Hint: use backticks.
+
+        >>> parse_table_structure('col Int32 MATERIALIZED expr')  # Unsupported MATERIALIZED
+        Traceback (most recent call last):
+        ...
+        tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 1:11.
+
+        >>> parse_table_structure('col Int32 TTL timestamp + INTERVAL 1 DAY')  # Unsupported TTL
+        Traceback (most recent call last):
+        ...
+        tinybird.tb.modules.datafile.common.SchemaSyntaxError: column TTL is not supported at 1:11.
+
+        >>> parse_table_structure('col Int32 NULL')  # Unsupported NULL
+        Traceback (most recent call last):
+        ...
+        tinybird.tb.modules.datafile.common.SchemaSyntaxError: NULL column syntax not supported at 1:11.
+        Hint: use Nullable(...).
+
+        >>> parse_table_structure('col Int32 NOT NULL')  # Unsupported NOT NULL
+        Traceback (most recent call last):
+        ...
+        tinybird.tb.modules.datafile.common.SchemaSyntaxError: NOT NULL column syntax not supported at 1:11.
+        Hint: Columns are not nullable by default.
+
+        >>> parse_table_structure('''
+        ...     col Array(Int32)
+        ...         CODEC(
+        ...             ZSTD''')  # Unclosed CODEC parenthesis across lines
+        Traceback (most recent call last):
+        ...
+        tinybird.tb.modules.datafile.common.SchemaSyntaxError: Expected closing ) at 4:17.
+
+        >>> parse_table_structure('''
+        ...     timestamp DateTime
+        ...         DEFAULT
+        ...         CODEC(ZSTD)''')  # Missing DEFAULT value with following CODEC
+        Traceback (most recent call last):
+        ...
+        tinybird.tb.modules.datafile.common.SchemaSyntaxError: Missing mandatory value for DEFAULT at 3:16.
+
+        >>> parse_table_structure('''
+        ...     col String
+        ...         DEFAULT 'test'
+        ...             MATERIALIZED
+        ...                 now()''')  # MATERIALIZED with heavy indentation
+        Traceback (most recent call last):
+        ...
+        tinybird.tb.modules.datafile.common.SchemaSyntaxError: MATERIALIZED columns are not supported at 4:13.
+
+        >>> parse_table_structure('''
+        ...     `column.with.dots`
+        ...              Int32
+        ...                  TTL
+        ...                      timestamp + INTERVAL 1 DAY''')  # TTL with increasing indentation
+        Traceback (most recent call last):
+        ...
+        tinybird.tb.modules.datafile.common.SchemaSyntaxError: column TTL is not supported at 4:18.
     """
     return _parse_table_structure(schema)