Introduction MySQL provides a dynamic environment that enables you to alter database items with a few basic commands. By learning how to use various statements, you can manage your databases with ease. This tutorial contains all the commands needed to rename a column in a MySQL database. Prerequisites ALTER TABLE is an essential command used to change the structure of a MySQL table. You can use it to add or delete columns, change the type of data within the columns, and even rename entire databases. The function that concerns us the most is how to utilize ALTER TABLE to rename a column. Statements give us additional control over the renaming process. The RENAME COLUMN and CHANGE statements both allow for the names of existing columns to be altered. The difference is that the CHANGE clause can also be used to alter the data types of a column. The simplest way to rename a column is to use the ALTER TABLE command with the RENAME COLUMN clause. This clause is available since MySQL version 8.0. Let’s illustrate its simple syntax. To change a column name, enter the following statement in your MySQL shell: ALTER TABLE table_name RENAME COLUMN old_column_name TO new_column_name;Replace table_name, old_column_name, and new_column_name with your table and column names. Keep in mind that you cannot rename a column to a name that already exists in the table. For instance, to change the column id into employee_id in the table employees, you would run: ALTER TABLE employees RENAME COLUMN id TO employ_id;The RENAME COLUMN statement can only be used to rename a column. If you need additional functions, such as changing the data definition, or position of a column, use the CHANGE clause instead.
Note: The word COLUMN is obligatory for the ALTER TABLE RENAME COLUMN command. ALTER TABLE RENAME is the existing syntax to rename the entire table. The CHANGE clause offers important additions to the renaming process. It can be used to rename a column and change the data type of that column with the same command. Enter the following command in your MySQL client shell to change the name of the column and its definition: ALTER TABLE table_name CHANGE old_column_name new_col_name Data Type;You can change the data type of the column or keep the existing one. In both cases you have to specify the data type as the element is mandatory. For example, to change the column id into employee_id which has the data type VARCHAR(25) in the table employees, you would run: ALTER TABLE employees CHANGE id employ_id VARCHAR(25);
Note: If you don't know the data type of the column you are renaming, check the structure of the table and the column definition using the DESCRIBE statement: DESCRIBE table_name;. You can use additional options to further manipulate table columns. The CHANGE also allows you to place the column in a different position in the table by using the optional FIRST | AFTER column_name clause. For example: ALTER TABLE table_name CHANGE old_column_name new_col_name Data Type AFTER column_x;With the command above you can changed the name of the column, changed the data type to y_data_type, and positioned the column after column_x. MySQL allows you to rename multiple columns with a single command. This option is possible with the RENAME and the CHANGE statement. To change the names of multiple columns using the RENAME COLUMN clause, use the syntax: ALTER TABLE table_name RENAME COLUMN old_column_name1 TO new_col_name1, RENAME COLUMN old_column_name2 TO new_col_name2, RENAME COLUMN old_column_name3 TO new_col_name3;To change the names of multiple columns using the CHANGE clause, use the syntax: ALTER TABLE table_name CHANGE old_column_name1 new_col_name1 Data Type, CHANGE old_column_name2 new_col_name2 Data Type, CHANGE old_column_name3 new_col_name3 Data Type;Conclusion You have successfully renamed an existing column in your MySQL database. This article has offered two options and provided the necessary commands. Understanding the essential ALTER TABLE statement is a precondition for exploring more complex expressions.
Categories: Table, View, & Sequence DDL
Modifies the properties, columns, or constraints for an existing table. See also:ALTER TABLE … ALTER COLUMN , CREATE TABLE , DROP TABLE , SHOW TABLES , DESCRIBE TABLE In this Topic:
ALTER TABLE [ IF EXISTS ] <name> RENAME TO <new_table_name> ALTER TABLE [ IF EXISTS ] <name> SWAP WITH <target_table_name> ALTER TABLE [ IF EXISTS ] <name> { clusteringAction | tableColumnAction | constraintAction } ALTER TABLE [ IF EXISTS ] <name> extTableColumnAction ALTER TABLE [ IF EXISTS ] <name> searchOptimizationAction ALTER TABLE [ IF EXISTS ] <name> SET [ STAGE_FILE_FORMAT = ( { FORMAT_NAME = '<file_format_name>' | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ] [ STAGE_COPY_OPTIONS = ( copyOptions ) ] [ DATA_RETENTION_TIME_IN_DAYS = <integer> ] [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ] [ CHANGE_TRACKING = { TRUE | FALSE } ] [ DEFAULT_DDL_COLLATION = '<collation_specification>' ] [ COMMENT = '<string_literal>' ] ALTER TABLE [ IF EXISTS ] <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ] ALTER TABLE [ IF EXISTS ] <name> UNSET TAG <tag_name> [ , <tag_name> ... ] ALTER TABLE [ IF EXISTS ] <name> UNSET { DATA_RETENTION_TIME_IN_DAYS | MAX_DATA_EXTENSION_TIME_IN_DAYS | CHANGE_TRACKING | DEFAULT_DDL_COLLATION | COMMENT | } [ , ... ] ALTER TABLE [ IF EXISTS ] <name> ADD ROW ACCESS POLICY <policy_name> ON (<col_name> [ , ... ]) ALTER TABLE [ IF EXISTS ] <name> DROP ROW ACCESS POLICY <policy_name> ALTER TABLE [ IF EXISTS ] <name> DROP ROW ACCESS POLICY <policy_name>, ADD ROW ACCESS POLICY <policy_name> ON (<col_name> [ , ... ]) ALTER TABLE [ IF EXISTS ] <name> DROP ALL ROW ACCESS POLICIES Where:
name Identifier for the table to alter. If the identifier contains spaces or special characters, the entire string must be enclosed in double quotes. Identifiers enclosed in double quotes are also case-sensitive. RENAME TO new_table_nameRenames the specified table with a new identifier that is not currently used by any other tables in the schema. For more details about table identifiers, see Identifier Requirements. You can move the object to a different database and/or schema while optionally renaming the object. To do so, specify a qualified new_name value that includes the new database and/or schema name in the form db_name.schema_name.object_name or schema_name.object_name, respectively.
Note
When an object (table, column, etc.) is renamed, other objects that reference it must be updated with the new name. SWAP WITH target_table_nameSwaps all content and metadata between two specified tables, including any integrity constraints defined for the tables. Also swap all access control privilege grants. The two tables are essentially renamed in a single transaction. Note that swapping a permanent or transient table with a temporary table, which persists only for the duration of the user session in which it was created, is not allowed. This restriction prevents a naming conflict that could occur when a temporary table is swapped with a permanent or transient table, and an existing permanent or transient table has the same name as the temporary table. To swap a permanent or transient table with a temporary table, use three ALTER TABLE ... RENAME TO statements: Rename table a to c, b to a, and then c to b.
Note To rename a table or swap two tables, the role used to perform the operation must have OWNERSHIP privileges on the table(s). In addition, renaming a table requires the CREATE TABLE privilege on the schema for the table. SET ...Specifies one or more properties/parameters to set for the table (separated by blank spaces, commas, or new lines): STAGE_FILE_FORMAT = ( FORMAT_NAME = 'file_format_name' ) or . STAGE_FILE_FORMAT = ( TYPE = CSV | JSON | AVRO | ORC | PARQUET | XML [ ... ] )Modifies the default file format for the table (for data loading and unloading), which can be either: FORMAT_NAME = file_format_nameSpecifies an existing file format object to use for loading/unloading data. The specified file format object determines the format type (CSV, JSON, etc.) and other format options for data files. Note that no additional format options are specified in the string. Instead, the named file format object defines the other file format options used for loading/unloading data. For more information, see CREATE FILE FORMAT. TYPE = CSV | JSON | AVRO | ORC | PARQUET | XML [ ... ]Specifies the type of files to load/unload. Additional format-specific options can be included in the string. For more details, see Format Type Options (in this topic).
Note FORMAT_NAME and TYPE are mutually exclusive; you can only specify one or the other for a table. STAGE_COPY_OPTIONS = ( ... )Modifies the copy options to use when loading data from files into the table. For more details, see Copy Options (in this topic). DATA_RETENTION_TIME_IN_DAYS = integerObject-level parameter that modifies the retention period for the table for Time Travel. For more details, see Understanding & Using Time Travel and Working with Temporary and Transient Tables. For a detailed description of this parameter, as well as more information about object parameters, see Parameters. Values:
Note A value of 0 effectively disables Time Travel for the table. MAX_DATA_EXTENSION_TIME_IN_DAYS = integerObject parameter that specifies the maximum number of days for which Snowflake can extend the data retention period for the table to prevent streams on the table from becoming stale. For a detailed description of this parameter, see MAX_DATA_EXTENSION_TIME_IN_DAYS. CHANGE_TRACKING = TRUE | FALSESpecifies to enable or disable change tracking on the table.
Specifies a default collation specification for any new columns added to the table. Setting the parameter does not change the collation specification for any existing columns. For more details about the parameter, see DEFAULT_DDL_COLLATION. TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ]Specifies the tag name and the tag string value. The tag value is always a string, and the maximum number of characters for the tag value is 256. For details about specifying tags in a statement, see Tag Quotas for Objects & Columns. COMMENT = 'string_literal'Adds a comment or overwrites the existing comment for the table. UNSET ...Specifies one or more properties/parameters to unset for the table, which resets them back to their defaults:
Note You cannot use UNSET to reset the file format and copy options. To reset these options, you must use SET. policy_nameIdentifier for the masking policy or row access policy; must be unique for your schema. ADD ROW ACCESS POLICY policy_name ON (col_name [ , ... ])Adds a row access policy to a table. At least one column name must be specified. Additional columns can be specified with a comma separating each column name. Use this expression to add a row access policy to both a table and an external table. DROP ROW ACCESS POLICY policy_nameDrops a row access policy from a table. Use this expression to drop a policy from both a table and an external table. DROP ALL ROW ACCESS POLICIESDrops all row access policy associations from a table. This expression is helpful when a row access policy is dropped from a schema before dropping the policy from a table. Use this expression to drop row access policy associations from both a table and an external table. CLUSTER BY ( expr [ , expr , ... ] ) Specifies (or modifies) one or more table columns or column expressions as the clustering key for the table. These are the columns/expressions for which clustering is maintained by Automatic Clustering.
Important Clustering keys are not intended or recommended for all tables; they typically benefit very large (i.e. multi-terabyte) tables. Before you specify a clustering key for a table, please see Understanding Snowflake Table Structures. RECLUSTER ...Deprecated Performs manual, incremental reclustering of a table that has a clustering key defined:
Note Only roles with the OWNERSHIP or INSERT privilege on a table can recluster the table. SUSPEND | RESUME RECLUSTER DROP CLUSTERING KEY Drops the clustering key for the table. For more information about clustering keys and reclustering, see Understanding Snowflake Table Structures. ADD [ COLUMN ] col_name col_data_type . [ DEFAULT | AUTOINCREMENT ... ] . [ inlineConstraint ] . [ [ WITH ] MASKING POLICY policy_name ] . [ [ WITH ] TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] ) ] [ , ...] Adds a new column that can optionally contain a default, inline constraint, masking policy, and/or one or more tags to the table. For additional details, see: This operation can be performed on multiple columns in the same command. RENAME COLUMN col_name to new_col_nameRenames the specified column to a new name that is not currently used for any other columns in the table. You cannot rename a column that is part of a clustering key. When an object (table, column, etc.) is renamed, other objects that reference it must be updated with the new name. ALTER | MODIFY [ COLUMN ] ...Modifies one or more properties for a column. This operation can be performed on multiple columns in the same command. For detailed syntax and examples for altering columns, see ALTER TABLE … ALTER COLUMN. USING ( col_name , cond_col_1 ... )Specifies the arguments to pass into the conditional masking policy SQL expression. The first column in the list specifies the column for the policy conditions to mask or tokenize the data and must match the column to which the masking policy is set. The additional columns specify the columns to evaluate to determine whether to mask or tokenize the data in each row of the query result when a query is made on the first column. If the USING clause is omitted, Snowflake treats the conditional masking policy as a normal masking policy. FORCEReplaces a masking policy that is currently set on a column with a different masking policy in a single statement. Note that using the FORCE keyword requires the data type of the policy in the ALTER TABLE statement (i.e. STRING) to match the data type of the masking policy currently set on the column (i.e. STRING). If a masking policy is not currently set on the column, specifying this keyword has no effect. For details, see: Replace a Masking Policy on a Column. DROP COLUMN col_name [ CASCADE | RESTRICT ]Removes the specified column from the table. Dropping a column is a metadata-only operation. It does not immediately re-write the micro-partition(s) and therefore does not immediately free up the space used by the column. Typically, the space within an individual micro-partition is freed the next time that the micro-partition is re-written, which is typically when a write is done either due to DML (INSERT, UPDATE, DELETE) or re-clustering.
For all other external table modifications, see ALTER EXTERNAL TABLE. ADD [ COLUMN ] <col_name> <col_type> AS ( <expr> ) [, ...]Adds a new column to the external table. This operation can be performed on multiple columns in the same command. col_nameString that specifies the column identifier (i.e. name). All the requirements for table identifiers also apply to column identifiers. For more details, see Identifier Requirements. col_typeString (constant) that specifies the data type for the column. The data type must match the result of expr for the column. For details about the data types that can be specified for table columns, see Data Types. exprString that specifies the expression for the column. When queried, the column returns results derived from this expression. External table columns are virtual columns, which are defined using an explicit expression. Add virtual columns as expressions using the VALUE column and/or the METADATA$FILENAME pseudocolumn: VALUEA VARIANT type column that represents a single row in the external file. CSVThe VALUE column structures each row as an object with elements identified by column position (i.e. {c1: <column_1_value>, c2: <column_2_value>, c3: <column_1_value> ...}). For example, add a VARCHAR column named mycol that references the first column in the staged CSV files: mycol varchar as (value:c1::varchar) Semi-structured dataEnclose element names and values in double-quotes. Traverse the path in the VALUE column using dot notation. For example, suppose the following represents a single row of semi-structured data in a staged file: { "a":"1", "b": { "c":"2", "d":"3" } } Add a VARCHAR column named mycol that references the nested repeating c element in the staged file: mycol varchar as (value:"b"."c"::varchar) METADATA$FILENAMEA pseudocolumn that identifies the name of each staged data file included in the external table, including its path in the stage. RENAME COLUMN col_name to new_col_nameRenames the specified column to a new name that is not currently used for any other columns in the external table. DROP COLUMN col_nameRemoves the specified column from the external table. ADD CONSTRAINT Adds an out-of-line integrity constraint to one or more columns in the table. To add an inline constraint (for a column), see Column Actions (in this topic). RENAME CONSTRAINT constraint_name TO new_constraint_nameRenames the specified constraint. ALTER | MODIFY CONSTRAINT ...Alters the properties for the specified constraint. DROP CONSTRAINT constraint_name | PRIMARY KEY | UNIQUE | FOREIGN KEY ( col_name [ , ... ] ) [ CASCADE | RESTRICT ]Drops the specified constraint for the specified column or set of columns. For detailed syntax and examples for adding or altering constraints, see CREATE | ALTER TABLE … CONSTRAINT. ADD SEARCH OPTIMIZATION Adds search optimization for the entire table or, if you specify the optional ON clause, for specific columns. Note:
ON search_method_with_target [, search_method_with_target ... ] DROP SEARCH OPTIMIZATION Removes search optimization for the entire table or, if you specify the optional ON clause, from specific columns. Note:
Specifies that you want to drop the search optimization configuration for specific columns or VARIANT fields (rather than dropping search optimization for the entire table). To identify the column configuration to drop, specify one of the following:
To specify more than one of these, use a comma between items. You can specify any combination of search methods with targets, column names, and expression IDs. For examples, see Dropping Search Optimization for Specific Columns.
Format type options are used for loading data into and unloading data out of tables. Depending on the file format type specified (STAGE_FILE_FORMAT = ( TYPE = ... )), you can include one or more of the following format-specific options (separated by blank spaces, commas, or new lines): COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE Use Data loading, data unloading, and external tables Definition
AUTO RECORD_DELIMITER = 'character' | NONE UseData loading, data unloading, and external tables DefinitionOne or more singlebyte or multibyte characters that separate records in an input file (data loading) or unloaded file (data unloading). Accepts common escape sequences or the following singlebyte or multibyte characters: Singlebyte charactersOctal values (prefixed by \\) or hex values (prefixed by 0x or \x). For example, for records delimited by the circumflex accent (^) character, specify the octal (\\136) or hex (0x5e) value. Multibyte charactersHex values (prefixed by \x). For example, for records delimited by the cent (¢) character, specify the hex (\xC2\xA2) value. The delimiter for RECORD_DELIMITER or FIELD_DELIMITER cannot be a substring of the delimiter for the other file format option (e.g. FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb'). The specified delimiter must be a valid UTF-8 character and not a random sequence of bytes. Also note that the delimiter is limited to a maximum of 20 characters. Also accepts a value of NONE. Default Data loadingNew line character. Note that “new line” is logical such that \r\n will be understood as a new line for files on a Windows platform. Data unloadingNew line character (\n). FIELD_DELIMITER = 'character' | NONE UseData loading, data unloading, and external tables DefinitionOne or more singlebyte or multibyte characters that separate fields in an input file (data loading) or unloaded file (data unloading). Accepts common escape sequences or the following singlebyte or multibyte characters: Singlebyte charactersOctal values (prefixed by \\) or hex values (prefixed by 0x or \x). For example, for records delimited by the circumflex accent (^) character, specify the octal (\\136) or hex (0x5e) value. Multibyte charactersHex values (prefixed by \x). For example, for records delimited by the cent (¢) character, specify the hex (\xC2\xA2) value. The delimiter for RECORD_DELIMITER or FIELD_DELIMITER cannot be a substring of the delimiter for the other file format option (e.g. FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb'). The specified delimiter must be a valid UTF-8 character and not a random sequence of bytes. Also note that the delimiter is limited to a maximum of 20 characters. Also accepts a value of NONE. Defaultcomma (,) FILE_EXTENSION = 'string' | NONE UseData unloading only DefinitionSpecifies the extension for files unloaded to a stage. Accepts any extension. The user is responsible for specifying a file extension that can be read by any desired software or services. Defaultnull, meaning the file extension is determined by the format type: .csv[compression], where compression is the extension added by the compression method, if COMPRESSION is set.
Note If the SINGLE copy option is TRUE, then the COPY command unloads a file without a file extension by default. To specify a file extension, provide a file name and extension in the internal_location or external_location path (e.g. copy into @stage/data.csv). SKIP_HEADER = integer UseData loading and external tables DefinitionNumber of lines at the start of the file to skip. Note that SKIP_HEADER does not use the RECORD_DELIMITER or FIELD_DELIMITER values to determine what a header line is; rather, it simply skips the specified number of CRLF (Carriage Return, Line Feed)-delimited lines in the file. RECORD_DELIMITER and FIELD_DELIMITER are then used to determine the rows of data to load. Default0 SKIP_BLANK_LINES = TRUE | FALSE UseData loading and external tables DefinitionBoolean that specifies to skip any blank lines encountered in the data files; otherwise, blank lines produce an end-of-record error (default behavior). Default: FALSE DATE_FORMAT = 'string' | AUTO UseData loading and unloading DefinitionDefines the format of date values in the data files (data loading) or table (data unloading). If a value is not specified or is AUTO, the value for the DATE_INPUT_FORMAT (data loading) or DATE_OUTPUT_FORMAT (data unloading) parameter is used. DefaultAUTO TIME_FORMAT = 'string' | AUTO UseData loading and unloading DefinitionDefines the format of time values in the data files (data loading) or table (data unloading). If a value is not specified or is AUTO, the value for the TIME_INPUT_FORMAT (data loading) or TIME_OUTPUT_FORMAT (data unloading) parameter is used. DefaultAUTO TIMESTAMP_FORMAT = string' | AUTO UseData loading and unloading DefinitionDefines the format of timestamp values in the data files (data loading) or table (data unloading). If a value is not specified or is AUTO, the value for the TIMESTAMP_INPUT_FORMAT (data loading) or TIMESTAMP_OUTPUT_FORMAT (data unloading) parameter is used. DefaultAUTO BINARY_FORMAT = HEX | BASE64 | UTF8 UseData loading and unloading DefinitionDefines the encoding format for binary input or output. The option can be used when loading data into or unloading data from binary columns in a table. DefaultHEX ESCAPE = 'character' | NONE UseData loading and unloading DefinitionA singlebyte character string used as the escape character for enclosed or unenclosed field values. An escape character invokes an alternative interpretation on subsequent characters in a character sequence. You can use the ESCAPE character to interpret instances of the FIELD_OPTIONALLY_ENCLOSED_BY character in the data as literals. Accepts common escape sequences, octal values, or hex values. Loading dataSpecifies the escape character for enclosed fields only. Specify the character used to enclose fields by setting FIELD_OPTIONALLY_ENCLOSED_BY.
Note This file format option supports singlebyte characters only. Note that UTF-8 character encoding represents high-order ASCII characters as multibyte characters. If your data file is encoded with the UTF-8 character set, you cannot specify a high-order ASCII character as the option value. In addition, if you specify a high-order ASCII character, we recommend that you set the ENCODING = 'string' file format option as the character encoding for your data files to ensure the character is interpreted correctly. Unloading dataIf this option is set, it overrides the escape character set for ESCAPE_UNENCLOSED_FIELD. DefaultNONE ESCAPE_UNENCLOSED_FIELD = 'character' | NONE UseData loading, data unloading, and external tables DefinitionA singlebyte character string used as the escape character for unenclosed field values only. An escape character invokes an alternative interpretation on subsequent characters in a character sequence. You can use the ESCAPE character to interpret instances of the FIELD_DELIMITER or RECORD_DELIMITER characters in the data as literals. The escape character can also be used to escape instances of itself in the data. Accepts common escape sequences, octal values, or hex values. Loading dataSpecifies the escape character for unenclosed fields only.
Note
If ESCAPE is set, the escape character set for that file format option overrides this option. Defaultbackslash (\\) TRIM_SPACE = TRUE | FALSE UseData loading and external tables DefinitionBoolean that specifies whether to remove white space from fields. For example, if your external database software encloses fields in quotes, but inserts a leading space, Snowflake reads the leading space rather than the opening quotation character as the beginning of the field (i.e. the quotation marks are interpreted as part of the string of field data). Set this option to TRUE to remove undesirable spaces during the data load. As another example, if leading or trailing spaces surround quotes that enclose strings, you can remove the surrounding spaces using this option and the quote character using the FIELD_OPTIONALLY_ENCLOSED_BY option. Note that any spaces within the quotes are preserved. For example, assuming FIELD_DELIMITER = '|' and FIELD_OPTIONALLY_ENCLOSED_BY = '"': |"Hello world"| /* loads as */ >Hello world< |" Hello world "| /* loads as */ > Hello world < | "Hello world" | /* loads as */ >Hello world< (the brackets in this example are not loaded; they are used to demarcate the beginning and end of the loaded strings) DefaultFALSE FIELD_OPTIONALLY_ENCLOSED_BY = 'character' | NONE UseData loading, data unloading, and external tables DefinitionCharacter used to enclose strings. Value can be NONE, single quote character ('), or double quote character ("). To use the single quote character, use the octal or hex representation (0x27) or the double single-quoted escape (''). When a field contains this character, escape it using the same character. For example, if the value is the double quote character and a field contains the string A "B" C, escape the double quotes as follows: Default NONE Data loading, data unloading, and external tables DefinitionString used to convert to and from SQL NULL:
\\N (i.e. NULL, which assumes the ESCAPE_UNENCLOSED_FIELD value is \\) ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether to generate a parsing error if the number of delimited columns (i.e. fields) in an input file does not match the number of columns in the corresponding table. If set to FALSE, an error is not generated and the load continues. If the file is successfully loaded:
This option assumes all the records within the input file are the same length (i.e. a file containing records of varying length return an error regardless of the value specified for this parameter). DefaultTRUE
Note When transforming data during loading (i.e. using a query as the source for the COPY command), this option is ignored. There is no requirement for your data files to have the same number and ordering of columns as your target table. REPLACE_INVALID_CHARACTERS = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether to replace invalid UTF-8 characters with the Unicode replacement character (�). If set to TRUE, Snowflake replaces invalid UTF-8 characters with the Unicode replacement character. If set to FALSE, the load operation produces an error when invalid UTF-8 character encoding is detected. DefaultFALSE EMPTY_FIELD_AS_NULL = TRUE | FALSE UseData loading, data unloading, and external tables Definition
TRUE SKIP_BYTE_ORDER_MARK = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether to skip the BOM (byte order mark), if present in a data file. A BOM is a character code at the beginning of a data file that defines the byte order and encoding form. If set to FALSE, Snowflake recognizes any BOM in data files, which could result in the BOM either causing an error or being merged into the first column in the table. DefaultTRUE ENCODING = 'string' UseData loading and external tables DefinitionString (constant) that specifies the character set of the source data when loading data into a table.
UTF8
Note Snowflake stores all data internally in the UTF-8 character set. The data is converted into UTF-8 before it is loaded into Snowflake. COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE Use Data loading and external tables Definition
AUTO DATE_FORMAT = 'string' | AUTO UseData loading only DefinitionDefines the format of date string values in the data files. If a value is not specified or is AUTO, the value for the DATE_INPUT_FORMAT parameter is used. This file format option is applied to the following actions only:
AUTO TIME_FORMAT = 'string' | AUTO UseData loading only DefinitionDefines the format of time string values in the data files. If a value is not specified or is AUTO, the value for the TIME_INPUT_FORMAT parameter is used. This file format option is applied to the following actions only:
AUTO TIMESTAMP_FORMAT = string' | AUTO UseData loading only DefinitionDefines the format of timestamp string values in the data files. If a value is not specified or is AUTO, the value for the TIMESTAMP_INPUT_FORMAT parameter is used. This file format option is applied to the following actions only:
AUTO BINARY_FORMAT = HEX | BASE64 | UTF8 UseData loading only DefinitionDefines the encoding format for binary string values in the data files. The option can be used when loading data into binary columns in a table. This file format option is applied to the following actions only:
HEX TRIM_SPACE = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether to remove leading and trailing white space from strings. For example, if your external database software encloses fields in quotes, but inserts a leading space, Snowflake reads the leading space rather than the opening quotation character as the beginning of the field (i.e. the quotation marks are interpreted as part of the string of field data). Set this option to TRUE to remove undesirable spaces during the data load. This file format option is applied to the following actions only when loading JSON data into separate columns using the MATCH_BY_COLUMN_NAME copy option. DefaultFALSE NULL_IF = ( 'string1' [ , 'string2' , ... ] ) UseData loading only DefinitionString used to convert to and from SQL NULL. Snowflake replaces these strings in the data load source with SQL NULL. To specify more than one string, enclose the list of strings in parentheses and use commas to separate each value. This file format option is applied to the following actions only when loading JSON data into separate columns using the MATCH_BY_COLUMN_NAME copy option. Note that Snowflake converts all instances of the value to NULL, regardless of the data type. For example, if 2 is specified as a value, all instances of 2 as either a string or number are converted. For example: NULL_IF = ('\\N', 'NULL', 'NUL', '') Note that this option can include empty strings. Default\\N (i.e. NULL, which assumes the ESCAPE_UNENCLOSED_FIELD value is \\) FILE_EXTENSION = 'string' | NONE UseData unloading only DefinitionSpecifies the extension for files unloaded to a stage. Accepts any extension. The user is responsible for specifying a file extension that can be read by any desired software or services. Defaultnull, meaning the file extension is determined by the format type: .json[compression], where compression is the extension added by the compression method, if COMPRESSION is set. ENABLE_OCTAL = TRUE | FALSE UseData loading only DefinitionBoolean that enables parsing of octal numbers. DefaultFALSE ALLOW_DUPLICATE = TRUE | FALSE UseData loading and external tables DefinitionBoolean that specifies to allow duplicate object field names (only the last one will be preserved). DefaultFALSE STRIP_OUTER_ARRAY = TRUE | FALSE UseData loading and external tables DefinitionBoolean that instructs the JSON parser to remove outer brackets (i.e. [ ]). DefaultFALSE STRIP_NULL_VALUES = TRUE | FALSE UseData loading and external tables DefinitionBoolean that instructs the JSON parser to remove object fields or array elements containing null values. For example, when set to TRUE:
FALSE REPLACE_INVALID_CHARACTERS = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether to replace invalid UTF-8 characters with the Unicode replacement character (�). The copy option performs a one-to-one character replacement. ValuesIf set to TRUE, Snowflake replaces invalid UTF-8 characters with the Unicode replacement character. If set to FALSE, the load operation produces an error when invalid UTF-8 character encoding is detected. DefaultFALSE IGNORE_UTF8_ERRORS = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether UTF-8 encoding errors produce error conditions. If set to TRUE, any invalid UTF-8 sequences are silently replaced with the Unicode character U+FFFD (i.e. “replacement character”).
Note This copy option removes all non-UTF-8 characters during the data load, but there is no guarantee of a one-to-one character replacement. We recommend using the REPLACE_INVALID_CHARACTERS copy option instead. DefaultFALSE SKIP_BYTE_ORDER_MARK = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether to skip the BOM (byte order mark), if present in a data file. A BOM is a character code at the beginning of a data file that defines the byte order and encoding form. If set to FALSE, Snowflake recognizes any BOM in data files, which could result in the BOM either causing an error or being merged into the first column in the table. DefaultTRUE COMPRESSION = AUTO | GZIP | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE Use Data loading only Definition
AUTO TRIM_SPACE = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether to remove leading and trailing white space from strings. For example, if your external database software encloses fields in quotes, but inserts a leading space, Snowflake reads the leading space rather than the opening quotation character as the beginning of the field (i.e. the quotation marks are interpreted as part of the string of field data). Set this option to TRUE to remove undesirable spaces during the data load. This file format option is applied to the following actions only when loading Avro data into separate columns using the MATCH_BY_COLUMN_NAME copy option. DefaultFALSE NULL_IF = ( 'string1' [ , 'string2' , ... ] ) UseData loading only DefinitionString used to convert to and from SQL NULL. Snowflake replaces these strings in the data load source with SQL NULL. To specify more than one string, enclose the list of strings in parentheses and use commas to separate each value. This file format option is applied to the following actions only when loading Avro data into separate columns using the MATCH_BY_COLUMN_NAME copy option. Note that Snowflake converts all instances of the value to NULL, regardless of the data type. For example, if 2 is specified as a value, all instances of 2 as either a string or number are converted. For example: NULL_IF = ('\\N', 'NULL', 'NUL', '') Note that this option can include empty strings. Default\\N (i.e. NULL, which assumes the ESCAPE_UNENCLOSED_FIELD value is \\) TRIM_SPACE = TRUE | FALSE Use Data loading and external tables DefinitionBoolean that specifies whether to remove leading and trailing white space from strings. For example, if your external database software encloses fields in quotes, but inserts a leading space, Snowflake reads the leading space rather than the opening quotation character as the beginning of the field (i.e. the quotation marks are interpreted as part of the string of field data). Set this option to TRUE to remove undesirable spaces during the data load. This file format option is applied to the following actions only when loading Orc data into separate columns using the MATCH_BY_COLUMN_NAME copy option. DefaultFALSE NULL_IF = ( 'string1' [ , 'string2' , ... ] ) UseData loading and external tables DefinitionString used to convert to and from SQL NULL. Snowflake replaces these strings in the data load source with SQL NULL. To specify more than one string, enclose the list of strings in parentheses and use commas to separate each value. This file format option is applied to the following actions only when loading Orc data into separate columns using the MATCH_BY_COLUMN_NAME copy option. Note that Snowflake converts all instances of the value to NULL, regardless of the data type. For example, if 2 is specified as a value, all instances of 2 as either a string or number are converted. For example: NULL_IF = ('\\N', 'NULL', 'NUL', '') Note that this option can include empty strings. Default\\N (i.e. NULL, which assumes the ESCAPE_UNENCLOSED_FIELD value is \\) COMPRESSION = AUTO | LZO | SNAPPY | NONE Use Data loading, data unloading, and external tables Definition
AUTO SNAPPY_COMPRESSION = TRUE | FALSE UseData unloading only AUTO | Unloaded files are compressed using the Snappy compression algorithm by default. SNAPPY | May be specified if unloading Snappy-compressed files. NONE | When loading data, indicates that the files have not been compressed. When unloading data, specifies that the unloaded files are not compressed. DefinitionBoolean that specifies whether unloaded file(s) are compressed using the SNAPPY algorithm.
Note Deprecated. Use COMPRESSION = SNAPPY instead. LimitationsOnly supported for data unloading operations. DefaultTRUE BINARY_AS_TEXT = TRUE | FALSE UseData loading and external tables DefinitionBoolean that specifies whether to interpret columns with no defined logical data type as UTF-8 text. When set to FALSE, Snowflake interprets these columns as binary data. DefaultTRUE TRIM_SPACE = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether to remove leading and trailing white space from strings. For example, if your external database software encloses fields in quotes, but inserts a leading space, Snowflake reads the leading space rather than the opening quotation character as the beginning of the field (i.e. the quotation marks are interpreted as part of the string of field data). Set this option to TRUE to remove undesirable spaces during the data load. This file format option is applied to the following actions only when loading Parquet data into separate columns using the MATCH_BY_COLUMN_NAME copy option. DefaultFALSE NULL_IF = ( 'string1' [ , 'string2' , ... ] ) UseData loading only DefinitionString used to convert to and from SQL NULL. Snowflake replaces these strings in the data load source with SQL NULL. To specify more than one string, enclose the list of strings in parentheses and use commas to separate each value. This file format option is applied to the following actions only when loading Parquet data into separate columns using the MATCH_BY_COLUMN_NAME copy option. Note that Snowflake converts all instances of the value to NULL, regardless of the data type. For example, if 2 is specified as a value, all instances of 2 as either a string or number are converted. For example: NULL_IF = ('\\N', 'NULL', 'NUL', '') Note that this option can include empty strings. Default\\N (i.e. NULL, which assumes the ESCAPE_UNENCLOSED_FIELD value is \\) COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE Use Data loading only Definition
AUTO IGNORE_UTF8_ERRORS = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether UTF-8 encoding errors produce error conditions. If set to TRUE, any invalid UTF-8 sequences are silently replaced with Unicode character U+FFFD (i.e. “replacement character”). DefaultFALSE Data loading only DefinitionBoolean that specifies whether the XML parser preserves leading and trailing spaces in element content. DefaultFALSE STRIP_OUTER_ELEMENT = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether the XML parser strips out the outer XML element, exposing 2nd level elements as separate documents. DefaultFALSE DISABLE_SNOWFLAKE_DATA = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether the XML parser disables recognition of Snowflake semi-structured data tags. DefaultFALSE DISABLE_AUTO_CONVERT = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether the XML parser disables automatic conversion of numeric and Boolean values from text to native representation. DefaultFALSE SKIP_BYTE_ORDER_MARK = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether to skip any BOM (byte order mark) present in an input file. A BOM is a character code at the beginning of a data file that defines the byte order and encoding form. If set to FALSE, Snowflake recognizes any BOM in data files, which could result in the BOM either causing an error or being merged into the first column in the table. DefaultTRUE
Copy options are used for loading data into and unloading data out of tables. You can specify one or more of the following copy options (separated by blank spaces, commas, or new lines): ON_ERROR = CONTINUE | SKIP_FILE | SKIP_FILE_num | 'SKIP_FILE_num%' | ABORT_STATEMENT UseData loading only DefinitionString (constant) that specifies the error handling for the load operation.
Important Carefully consider the ON_ERROR copy option value. The default value is appropriate in common scenarios, but is not always the best option. Values
ABORT_STATEMENT SnowpipeSKIP_FILE SIZE_LIMIT = num UseData loading only DefinitionNumber (> 0) that specifies the maximum size (in bytes) of data to be loaded for a given COPY statement. When the threshold is exceeded, the COPY operation discontinues loading files. This option is commonly used to load a common group of files using multiple COPY statements. For each statement, the data load continues until the specified SIZE_LIMIT is exceeded, before moving on to the next statement. For example, suppose a set of files in a stage path were each 10 MB in size. If multiple COPY statements set SIZE_LIMIT to 25000000 (25 MB), each would load 3 files. That is, each COPY operation would discontinue after the SIZE_LIMIT threshold was exceeded. Note that at least one file is loaded regardless of the value specified for SIZE_LIMIT unless there is no file to be loaded. Defaultnull (no size limit) PURGE = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether to remove the data files from the stage automatically after the data is loaded successfully. If this option is set to TRUE, note that a best effort is made to remove successfully loaded data files. If the purge operation fails for any reason, no error is returned currently. We recommend that you list staged files periodically (using LIST) and manually remove successfully loaded files, if any exist. DefaultFALSE RETURN_FAILED_ONLY = TRUE | FALSE UseData loading only DefinitionBoolean that specifies whether to return only files that have failed to load in the statement result. DefaultFALSE MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE UseData loading only DefinitionString that specifies whether to load semi-structured data into columns in the target table that match corresponding columns represented in the data. This copy option is supported for the following data formats: For a column to match, the following criteria must be true:
Load semi-structured data into columns in the target table that match corresponding columns represented in the data. Column names are either case-sensitive (CASE_SENSITIVE) or case-insensitive (CASE_INSENSITIVE). The COPY operation verifies that at least one column in the target table matches a column represented in the data files. If a match is found, the values in the data files are loaded into the column or columns. If no match is found, a set of NULL values for each record in the files is loaded into the table.
Note
The COPY operation loads the semi-structured data into a variant column or, if a query is included in the COPY statement, transforms the data.
Note The following limitations currently apply: Default NONE ENFORCE_LENGTH = TRUE | FALSE UseData loading only DefinitionAlternative syntax for TRUNCATECOLUMNS with reverse logic (for compatibility with other systems) Boolean that specifies whether to truncate text strings that exceed the target column length:
This copy option supports CSV data, as well as string values in semi-structured data when loaded into separate columns in relational tables.
Note
TRUE TRUNCATECOLUMNS = TRUE | FALSE UseData loading only DefinitionAlternative syntax for ENFORCE_LENGTH with reverse logic (for compatibility with other systems) Boolean that specifies whether to truncate text strings that exceed the target column length:
This copy option supports CSV data, as well as string values in semi-structured data when loaded into separate columns in relational tables.
Note
FALSE FORCE = TRUE | FALSE UseData loading only DefinitionBoolean that specifies to load all files, regardless of whether they’ve been loaded previously and have not changed since they were loaded. Note that this option reloads files, potentially duplicating data in a table. DefaultFALSE
Rename table t1 to a1:
Swap tables t1 and t2:
Add columns to table t1, then rename a column and drop a column in the table:
Similar to the last example, but add, rename, and drop a column in external table exttable1:
Change the order of the clustering key for a table:
The following example adds a row access policy on a table while specifying a single column. After setting the policy, you can verify by checking the information schema.
The following example adds a row access policy while specifying two columns in a single table.
The following example drops a row access policy from a table. Verify the policies were dropped by querying the information schema.
The following example shows how to combine adding and dropping row access policies in a single SQL statement for a table. Verify the results by checking the information schema.
|