@@ -133,6 +133,10 @@ def json_extract_array(
133
133
`STRING` or `JSON` values. This function uses single quotes and brackets to
134
134
escape invalid JSONPath characters in JSON keys.
135
135
136
+ .. deprecated:: 2.5.0
137
+ The ``json_extract_array`` is deprecated and will be removed in a future version.
138
+ Use ``json_query_array`` instead.
139
+
136
140
**Examples:**
137
141
138
142
>>> import bigframes.pandas as bpd
@@ -172,6 +176,11 @@ def json_extract_array(
172
176
Returns:
173
177
bigframes.series.Series: A new Series with the parsed arrays from the input.
174
178
"""
179
+ msg = (
180
+ "The `json_extract_array` is deprecated and will be removed in a future version. "
181
+ "Use `json_query_array` instead."
182
+ )
183
+ warnings .warn (bfe .format_message (msg ), category = UserWarning )
175
184
return input ._apply_unary_op (ops .JSONExtractArray (json_path = json_path ))
176
185
177
186
@@ -273,6 +282,56 @@ def json_query(
273
282
return input ._apply_unary_op (ops .JSONQuery (json_path = json_path ))
274
283
275
284
285
+ def json_query_array (
286
+ input : series .Series ,
287
+ json_path : str = "$" ,
288
+ ) -> series .Series :
289
+ """Extracts a JSON array and converts it to a SQL array of JSON-formatted
290
+ `STRING` or `JSON` values. This function uses double quotes to escape invalid
291
+ JSONPath characters in JSON keys. For example: `"a.b"`.
292
+
293
+ **Examples:**
294
+
295
+ >>> import bigframes.pandas as bpd
296
+ >>> import bigframes.bigquery as bbq
297
+ >>> bpd.options.display.progress_bar = None
298
+
299
+ >>> s = bpd.Series(['[1, 2, 3]', '[4, 5]'])
300
+ >>> bbq.json_query_array(s)
301
+ 0 ['1' '2' '3']
302
+ 1 ['4' '5']
303
+ dtype: list<item: string>[pyarrow]
304
+
305
+ >>> s = bpd.Series([
306
+ ... '{"fruits": [{"name": "apple"}, {"name": "cherry"}]}',
307
+ ... '{"fruits": [{"name": "guava"}, {"name": "grapes"}]}'
308
+ ... ])
309
+ >>> bbq.json_query_array(s, "$.fruits")
310
+ 0 ['{"name":"apple"}' '{"name":"cherry"}']
311
+ 1 ['{"name":"guava"}' '{"name":"grapes"}']
312
+ dtype: list<item: string>[pyarrow]
313
+
314
+ >>> s = bpd.Series([
315
+ ... '{"fruits": {"color": "red", "names": ["apple","cherry"]}}',
316
+ ... '{"fruits": {"color": "green", "names": ["guava", "grapes"]}}'
317
+ ... ])
318
+ >>> bbq.json_query_array(s, "$.fruits.names")
319
+ 0 ['"apple"' '"cherry"']
320
+ 1 ['"guava"' '"grapes"']
321
+ dtype: list<item: string>[pyarrow]
322
+
323
+ Args:
324
+ input (bigframes.series.Series):
325
+ The Series containing JSON data (as native JSON objects or JSON-formatted strings).
326
+ json_path (str):
327
+ The JSON path identifying the data that you want to obtain from the input.
328
+
329
+ Returns:
330
+ bigframes.series.Series: A new Series with the parsed arrays from the input.
331
+ """
332
+ return input ._apply_unary_op (ops .JSONQueryArray (json_path = json_path ))
333
+
334
+
276
335
def json_value (
277
336
input : series .Series ,
278
337
json_path : str ,
0 commit comments