You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/t-sql/functions/string-split-transact-sql.md
+93-25Lines changed: 93 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,9 @@
1
1
---
2
-
title: "STRING_SPLIT (Transact-SQL) | Microsoft Docs"
2
+
title: "STRING_SPLIT (Transact-SQL)"
3
3
description: "Transact-SQL reference for the STRING_SPLIT function. This table-valued function splits a string into substrings based on a character delimiter."
@@ -32,39 +31,54 @@ STRING_SPLIT requires the compatibility level to be at least 130. When the level
32
31
To change the compatibility level of a database, refer to [View or Change the Compatibility Level of a Database](../../relational-databases/databases/view-or-change-the-compatibility-level-of-a-database.md).
33
32
34
33
> [!NOTE]
35
-
> Compatibility configuration is not needed for STRING_SPLIT in Azure Synapse Analytics.
34
+
> Compatibility configuration is not needed for `STRING_SPLIT` in Azure Synapse Analytics.
36
35
37
36
![Topic link icon](../../database-engine/configure-windows/media/topic-link.gif"Topic link icon")[Transact-SQL Syntax Conventions](../../t-sql/language-elements/transact-sql-syntax-conventions-transact-sql.md)
Is an [expression](../../t-sql/language-elements/expressions-transact-sql.md) of any character type (for example, **nvarchar**, **varchar**, **nchar**, or **char**).
51
48
52
-
*separator*
49
+
####*separator*
53
50
Is a single character [expression](../../t-sql/language-elements/expressions-transact-sql.md) of any character type (for example, **nvarchar(1)**, **varchar(1)**, **nchar(1)**, or **char(1)**) that is used as separator for concatenated substrings.
54
-
51
+
52
+
#### *enable_ordinal*
53
+
An **int** or **bit**[expression](../../t-sql/language-elements/expressions-transact-sql.md) that serves as a flag to enable or disable the `ordinal` output column. A value of 1 enables the `ordinal` column. If *enable_ordinal* is omitted, `NULL`, or has a value of 0, the `ordinal` column is disabled.
54
+
55
+
> [!NOTE]
56
+
> The *enable_ordinal* argument and `ordinal` output column are currently only supported in Azure SQL Database, Azure SQL Managed Instance, and Azure Synapse Analytics (serverless SQL pool only).
57
+
55
58
## Return Types
56
59
57
-
Returns a single-column table whose rows are the substrings. The name of the column is **value**. Returns **nvarchar** if any of the input arguments are either **nvarchar** or **nchar**. Otherwise returns **varchar**. The length of the return type is the same as the length of the string argument.
60
+
If the `ordinal` output column is not enabled, STRING_SPLIT returns a single-column table whose rows are the substrings. The name of the column is `value`. It returns **nvarchar** if any of the input arguments are either **nvarchar** or **nchar**. Otherwise, it returns **varchar**. The length of the return type is the same as the length of the *string* argument.
61
+
62
+
If the *enable_ordinal* argument is passed a value of 1, a second column named `ordinal` is returned that consists of the 1-based index values of each substring's position in the input string. The return type is **bigint**.
63
+
58
64
59
65
## Remarks
60
66
61
-
**STRING_SPLIT** inputs a string that has delimited substrings, and inputs one character to use as the delimiter or separator. STRING_SPLIT outputs a single-column table whose rows contain the substrings. The name of the output column is **value**.
67
+
STRING_SPLIT inputs a string that has delimited substrings and inputs one character to use as the delimiter or separator. Optionally, the function supports a third argument with a value of 0 or 1 that disables or enables, respectively, the `ordinal` output column.
68
+
69
+
STRING_SPLIT outputs a single-column or double-column table, depending on the *enable_ordinal* argument.
62
70
63
-
The output rows might be in any order. The order is _not_ guaranteed to match the order of the substrings in the input string. You can override the final sort order by using an ORDER BY clause on the SELECT statement (`ORDER BY value`).
71
+
- If *enable_ordinal* is `NULL`, omitted, or has a value of 0, STRING_SPLIT returns a single-column table whose rows contain the substrings. The name of the output column is `value`.
72
+
73
+
- If *enable_ordinal* has a value of 1, the function returns a two-column table, including the `ordinal` column that consists of the 1-based index values of the substrings in the original input string.
74
+
75
+
Note that the *enable_ordinal* argument must be a constant value, not a column or variable. It must also be either a **bit** or **int** data type with a value of 0 or 1. Otherwise, the function will raise an error.
76
+
77
+
The output rows might be in any order. The order is _not_ guaranteed to match the order of the substrings in the input string. You can override the final sort order by using an ORDER BY clause on the SELECT statement, for example, `ORDER BY value` or `ORDER BY ordinal`.
64
78
65
79
0x0000 (**char(0)**) is an undefined character in Windows collations and cannot be included in STRING_SPLIT.
66
80
67
-
Empty zero-length substrings are present when the input string contains two or more consecutive occurrences of the delimiter character. Empty substrings are treated the same as are plain substrings. You can filter out any rows that contain the empty substring by using the WHERE clause (`WHERE value <> ''`). If the input string is NULL, the STRING_SPLIT table-valued function returns an empty table.
81
+
Empty zero-length substrings are present when the input string contains two or more consecutive occurrences of the delimiter character. Empty substrings are treated the same as are plain substrings. You can filter out any rows that contain the empty substring by using the WHERE clause, for example `WHERE value <> ''`. If the input string is `NULL`, the STRING_SPLIT table-valued function returns an empty table.
68
82
69
83
As an example, the following SELECT statement uses the space character as the separator:
70
84
@@ -74,7 +88,7 @@ SELECT value FROM STRING_SPLIT('Lorem ipsum dolor sit amet.', ' ');
74
88
75
89
In a practice run, the preceding SELECT returned following result table:
76
90
77
-
|value|
91
+
|**value**|
78
92
| :-- |
79
93
|Lorem|
80
94
|ipsum|
@@ -83,6 +97,23 @@ In a practice run, the preceding SELECT returned following result table:
83
97
|amet.|
84
98
| |
85
99
100
+
The following example enables the `ordinal` column by passing 1 for the optional third argument:
101
+
102
+
```sql
103
+
SELECT value FROM STRING_SPLIT('Lorem ipsum dolor sit amet.', '', 1);
104
+
```
105
+
106
+
This statement then returns the following result table:
107
+
108
+
|**value**|**ordinal**|
109
+
| :-- | :-- |
110
+
|Lorem|1|
111
+
|ipsum|2|
112
+
|dolor|3|
113
+
|sit|4|
114
+
|amet.|5|
115
+
| ||
116
+
86
117
## Examples
87
118
88
119
### A. Split comma-separated value string
@@ -103,7 +134,7 @@ STRING_SPLIT will return empty string if there is nothing between separator. Con
103
134
104
135
Product table has a column with comma-separate list of tags shown in the following example:
> The order of the output may vary as the order is _not_ guaranteed to match the order of the substrings in the input string.
134
-
163
+
>[!NOTE]
164
+
> The order of the output may vary as the order is _not_ guaranteed to match the order of the substrings in the input string.
165
+
135
166
### C. Aggregation by values
136
167
137
168
Users must create a report that shows the number of products per each tag, ordered by number of products, and to filter only the tags with more than two products.
138
169
139
170
```sql
140
-
SELECT value as tag, COUNT(*) AS [Number of articles]
171
+
SELECT value as tag, COUNT(*) AS [number_of_articles]
0 commit comments