ListAccessor オブジェクトは、次の例に示すように、Series オブジェクトの list プロパティを使用して、各リスト要素に対してオペレーションを実行する際に役立ちます。
importbigframes.pandasasbpds=bpd.Series([[1,2,3],[4,5],[6]])# dtype: list<item: int64>[pyarrow]# Access the first elements of each lists.list[0]# 0 1# 1 4# 2 6# dtype: Int64# Get the lengths of each lists.list.len()# 0 3# 1 2# 2 1# dtype: Int64
importbigframes.pandasasbpdstructs=[{"id":101,"category":"A"},{"id":102,"category":"B"},{"id":103,"category":"C"},]s=bpd.Series(structs)# Get the 'id' field of each structs.struct.field("id")# 0 101# 1 102# 2 103# Name: id, dtype: Int64
アクセスする struct フィールドが他の Series プロパティと区別できる場合は、次の例に示すように struct の呼び出しをスキップできます。
importbigframes.pandasasbpdstructs=[{"id":101,"category":"A"},{"id":102,"category":"B"},{"id":103,"category":"C"},]s=bpd.Series(structs)# not explicitly using the "struct" propertys.id# 0 101# 1 102# 2 103# Name: id, dtype: Int64
importbigframes.pandasasbpds=bpd.Series(["abc","de","1"])# dtype: string[pyarrow]# Get the first character of each strings.str[0]# 0 a# 1 d# 2 1# dtype: string# Check whether there are only alphabetic characters in each strings.str.isalpha()# 0 True# 1 True# 2 False# dtype: boolean# Cast the alphabetic characters to their upper cases for each strings.str.upper()# 0 ABC# 1 DE# 2 1# dtype: string
[[["わかりやすい","easyToUnderstand","thumb-up"],["問題の解決に役立った","solvedMyProblem","thumb-up"],["その他","otherUp","thumb-up"]],[["わかりにくい","hardToUnderstand","thumb-down"],["情報またはサンプルコードが不正確","incorrectInformationOrSampleCode","thumb-down"],["必要な情報 / サンプルがない","missingTheInformationSamplesINeed","thumb-down"],["翻訳に関する問題","translationIssue","thumb-down"],["その他","otherDown","thumb-down"]],["最終更新日 2025-09-04 UTC。"],[],[],null,["# Use the BigQuery DataFrames data type system\n============================================\n\nThe BigQuery DataFrames data type system is built upon BigQuery data\ntypes. This design ensures seamless integration and alignment with the\nGoogle Cloud data warehouse, reflecting the built-in types used for data\nstorage in BigQuery.\n\nType mappings\n-------------\n\nThe following table shows data type equivalents in BigQuery,\nBigQuery DataFrames, and other Python libraries as well as their levels\nof support:\n\n| **Note:** BigQuery DataFrames doesn't support the following BigQuery data types: `INTERVAL` and `RANGE`. All other BigQuery data types display as the object type.\n\n### Type conversions\n\nWhen used with local data, BigQuery DataFrames converts data types to\ntheir corresponding BigQuery DataFrames equivalents wherever a\n[type mapping is defined](#type-mappings), as shown in the following example: \n\n import pandas as pd\n\n import bigframes.pandas as bpd\n\n s = pd.Series([pd.Timestamp(\"20250101\")])\n assert s.dtype == \"datetime64[ns]\"\n assert bpd.read_pandas(s).dtype == \"timestamp[us][pyarrow]\"\n\nPyArrow dictates behavior when there are discrepancies between the data type\nequivalents. In rare cases when the Python built-in type functions differently\nfrom its PyArrow counterpart, BigQuery DataFrames generally favors the\nPyArrow behavior to ensure consistency.\n\nThe following code sample uses the `datetime.date + timedelta` operation to\nshow that, unlike the Python datetime library that still returns a date\ninstance, BigQuery DataFrames follows the PyArrow behavior by returning\na timestamp instance: \n\n import datetime\n\n import pandas as pd\n\n import bigframes.pandas as bpd\n\n s = pd.Series([datetime.date(2025, 1, 1)])\n s + pd.Timedelta(hours=12)\n # 0\t2025-01-01\n # dtype: object\n\n bpd.read_pandas(s) + pd.Timedelta(hours=12)\n # 0 2025-01-01 12:00:00\n # dtype: timestamp[us][pyarrow]\n\nSpecial types\n-------------\n\nThe following sections describe the special data types that\nBigQuery DataFrames uses.\n\n### JSON\n\nWithin BigQuery DataFrames, columns using the BigQuery\n[JSON format](/bigquery/docs/reference/standard-sql/data-types#json_type)\n(a lightweight standard) are represented by `pandas.ArrowDtype`. The exact\nunderlying Arrow type depends on your library versions. Older environments\ntypically use `db_dtypes.JSONArrowType()` for compatibility, which is an Arrow\nextension type that acts as a light wrapper around `pa.string()`. In contrast,\nnewer setups (pandas 3.0 and later and PyArrow 19.0 and later) utilize the more\nrecent `pa.json_(pa.string())` representation.\n\n### `timedelta`\n\nThe `timedelta` type lacks a direct equivalent within the\nBigQuery native type system. To manage duration data,\nBigQuery DataFrames utilizes the `INT64` type as the underlying storage\nformat in BigQuery tables. You can expect the results of your\ncomputations to be consistent with the behavior you would expect from\nequivalent operations performed with the pandas library.\n\nYou can directly load `timedelta` values into BigQuery DataFrames and\n`Series` objects, as shown in the following example: \n\n import pandas as pd\n\n import bigframes.pandas as bpd\n\n s = pd.Series([pd.Timedelta(\"1s\"), pd.Timedelta(\"2m\")])\n bpd.read_pandas(s)\n # 0 0 days 00:00:01\n # 1 0 days 00:02:00\n # dtype: duration[us][pyarrow]\n\nUnlike pandas, BigQuery DataFrames only supports `timedelta` values with\nmicrosecond precision. If your data includes nanoseconds, you must round them to\navoid potential exceptions, as shown in the following example: \n\n import pandas as pd\n\n s = pd.Series([pd.Timedelta(\"999ns\")])\n bpd.read_pandas(s.dt.round(\"us\"))\n # 0 0 days 00:00:00.000001\n # dtype: duration[us][pyarrow]\n\nYou can use the `bigframes.pandas.to_timedelta` function to cast a\nBigQuery DataFrames `Series` object to the `timedelta` type, as shown\nin the following example: \n\n import bigframes.pandas as bpd\n\n bpd.to_timedelta([1, 2, 3], unit=\"s\")\n # 0 0 days 00:00:01\n # 1 0 days 00:00:02\n # 2 0 days 00:00:03\n # dtype: duration[us][pyarrow]\n\nWhen you load data containing `timedelta` values to a BigQuery table, the\nvalues are converted to microseconds and stored in `INT64` columns. To\npreserve the type information, BigQuery DataFrames appends the\n`#microseconds` string to the descriptions of these columns. Some operations,\nsuch as SQL query executions and UDF invocations, don't preserve column\ndescriptions, and the `timedelta` type information is lost after these\noperations are completed.\n\nTools for composite types\n-------------------------\n\nFor certain composite types, BigQuery DataFrames provides tools that\nlet you access and process the elemental values within those types.\n\n### List accessor\n\nThe `ListAccessor` object can help you perform operations on each list element\nby using the list property of the `Series` object, as shown in the\nfollowing example: \n\n import bigframes.pandas as bpd\n\n s = bpd.Series([[1, 2, 3], [4, 5], [6]]) # dtype: list\u003citem: int64\u003e[pyarrow]\n\n # Access the first elements of each list\n s.list[0]\n # 0 1\n # 1 4\n # 2 6\n # dtype: Int64\n\n # Get the lengths of each list\n s.list.len()\n # 0 3\n # 1 2\n # 2 1\n # dtype: Int64\n\n### Struct accessor\n\nThe `StructAccessor` object can access and process fields in a series of\nstructs. The API accessor object is `series.struct`, as shown in the\nfollowing example: \n\n import bigframes.pandas as bpd\n\n structs = [\n {\"id\": 101, \"category\": \"A\"},\n {\"id\": 102, \"category\": \"B\"},\n {\"id\": 103, \"category\": \"C\"},\n ]\n s = bpd.Series(structs)\n # Get the 'id' field of each struct\n s.struct.field(\"id\")\n # 0 101\n # 1 102\n # 2 103\n # Name: id, dtype: Int64\n\nIf the `struct` field you plan to access is unambiguous from other `Series`\nproperties, you can skip calling `struct`, as shown in the following example: \n\n import bigframes.pandas as bpd\n\n structs = [\n {\"id\": 101, \"category\": \"A\"},\n {\"id\": 102, \"category\": \"B\"},\n {\"id\": 103, \"category\": \"C\"},\n ]\n s = bpd.Series(structs)\n\n # not explicitly using the \"struct\" property\n s.id\n # 0 101\n # 1 102\n # 2 103\n # Name: id, dtype: Int64\n\nHowever, it's a best practice to use `struct` for accessing fields, because\nit makes your code easier to understand and less error-prone.\n\n### String accessor\n\nYou can access the `StringAccessor` object with the `str` property on a `Series`\nobject, as shown in the following example: \n\n import bigframes.pandas as bpd\n\n s = bpd.Series([\"abc\", \"de\", \"1\"]) # dtype: string[pyarrow]\n\n # Get the first character of each string\n s.str[0]\n # 0 a\n # 1 d\n # 2 1\n # dtype: string\n\n # Check whether there are only alphabetic characters in each string\n s.str.isalpha()\n # 0 True\n # 1 True\n # 2 False\n # dtype: boolean\n\n # Cast the alphabetic characters to their upper cases for each string\n s.str.upper()\n # 0 ABC\n # 1 DE\n # 2 1\n # dtype: string\n\n### Geography accessor\n\nBigQuery DataFrames provides a `GeographyAccessor` object that shares\nsimilar APIs with the GeoSeries structure provided by the GeoPandas library. You\ncan invoke the `GeographyAccessor` object with the `geo` property on a `Series`\nobject, as shown in the following example: \n\n from shapely.geometry import Point\n\n import bigframes.pandas as bpd\n\n s = bpd.Series([Point(1, 0), Point(2, 1)]) # dtype: geometry\n\n s.geo.y\n # 0 0.0\n # 1 1.0\n # dtype: Float64\n\nWhat's next\n-----------\n\n- Learn how to [use BigQuery DataFrames](/bigquery/docs/use-bigquery-dataframes).\n- Learn about [BigQuery DataFrames sessions and I/O](/bigquery/docs/dataframes-sessions-io).\n- Learn how to [visualize graphs using BigQuery DataFrames](/bigquery/docs/dataframes-visualizations).\n- Explore the [BigQuery DataFrames API reference](/python/docs/reference/bigframes/latest/summary_overview)."]]
