Pivot Tables

PivotTable

資料透視表。

JSON 表示法 
{
  "rows": [
    {
      object (PivotGroup)
    }
  ],
  "columns": [
    {
      object (PivotGroup)
    }
  ],
  "criteria": {
    integer: {
      object (PivotFilterCriteria)
    },
    ...
  },
  "filterSpecs": [
    {
      object (PivotFilterSpec)
    }
  ],
  "values": [
    {
      object (PivotValue)
    }
  ],
  "valueLayout": enum (PivotValueLayout),
  "dataExecutionStatus": {
    object (DataExecutionStatus)
  },

  // Union field source_data can be only one of the following:
  "source": {
    object (GridRange)
  },
  "dataSourceId": string
  // End of list of possible types for union field source_data.
}
欄位
rows[]

object (PivotGroup)

資料透視表中的每一列都會分組。

columns[]

object (PivotGroup)

資料透視表中的每個資料欄分組。

criteria
(deprecated)

map (key: integer, value: object ( PivotFilterCriteria))

每個來源資料欄偏移的篩選器對應 (選用)。

系統會先套用篩選器，再將資料匯總至資料透視表。對應的索引鍵是您要篩選來源範圍的資料欄偏移值，而值則是該資料欄的條件。

舉例來說，如果來源是 C10:E15，0 的鍵會包含 C 欄的篩選條件，1 的鍵則用於資料欄 D。

這個欄位已淘汰，並改用 filterSpecs。
filterSpecs[]

object (PivotFilterSpec)

系統會先套用至來源資料欄的篩選器，再匯總資料透視表的資料。

criteria 和 filterSpecs 都會填入回應。如果您在更新要求中同時指定這兩個欄位，則系統會優先採用這個欄位。
values[]

object (PivotValue)

要納入資料透視表的值清單。

valueLayout

enum (PivotValueLayout)

值應為水平 (以欄為單位) 或垂直 (以資料列形式) 列出。

dataExecutionStatus

object (DataExecutionStatus)

僅供輸出。資料來源資料透視表的資料執行狀態。
聯集欄位 source_data。資料透視表的資料來源。source_data 只能採用下列其中一種設定：
source

object (GridRange)

資料透視表讀取資料的範圍。

dataSourceId

string

資料透視表讀取資料時的資料來源 ID。

PivotGroup

資料透視表中的單一群組 (列或欄)。

JSON 表示法 
{
  "showTotals": boolean,
  "valueMetadata": [
    {
      object (PivotGroupValueMetadata)
    }
  ],
  "sortOrder": enum (SortOrder),
  "valueBucket": {
    object (PivotGroupSortValueBucket)
  },
  "repeatHeadings": boolean,
  "label": string,
  "groupRule": {
    object (PivotGroupRule)
  },
  "groupLimit": {
    object (PivotGroupLimit)
  },

  // Union field source can be only one of the following:
  "sourceColumnOffset": integer,
  "dataSourceColumnReference": {
    object (DataSourceColumnReference)
  }
  // End of list of possible types for union field source.
}
欄位
showTotals

boolean

如果資料透視表應包含此分組的總計，則為 True。

valueMetadata[]

object (PivotGroupValueMetadata)

關於分組中值的中繼資料。
sortOrder

enum (SortOrder)

這個群組中值的排序順序。
valueBucket

object (PivotGroupSortValueBucket)

對應資料透視表的排序依據值區。如未指定，系統會按照群組值的字母順序排序。
repeatHeadings

boolean

如果此資料透視表中的標題應重複，則為 True。這僅適用於資料列分組，且會略過資料欄。

根據預設，我們會避免在內容層級相同的較高層級顯示標題，藉此盡量減少重複出現的標題。舉例來說，即使下方的第三列對應了「3 季第 1 季」，但不會顯示「Q1」，因為此列與先前的資料列會重複。如果將重複標題設為 True，會導致「2 月」和「3 月」重複「Q1」。 

+--------------+
| Q1     | Jan |
|        | Feb |
|        | Mar |
+--------+-----+
| Q1 Total     |
+--------------+
label

string

要用於可自訂列/欄群組的標籤。舉例來說，在下列資料透視表中，資料列標籤為 Region (可重新命名為 State)，而資料欄標籤為 Product (可重新命名為 Item)。2017 年 12 月前建立的資料透視表沒有標頭標籤。如要在現有的資料透視表中新增標頭標籤，請先刪除現有的資料透視表，再使用相同參數建立新的資料透視表。 

+--------------+---------+-------+
| SUM of Units | Product |       |
| Region       | Pen     | Paper |
+--------------+---------+-------+
| New York     |     345 |    98 |
| Oregon       |     234 |   123 |
| Tennessee    |     531 |   415 |
+--------------+---------+-------+
| Grand Total  |    1110 |   636 |
+--------------+---------+-------+
groupRule

object (PivotGroupRule)

要套用至這個列/欄群組的群組規則。

groupLimit

object (PivotGroupLimit)

要套用至這個資料透視表的資料列或資料欄數量上限。

聯集欄位 source。資料透視表群組的資料來源。source 只能採用下列其中一種設定：
sourceColumnOffset

integer

這個分組依據的來源範圍資料欄偏移值。

舉例來說，如果來源是 C10:E15，則 sourceColumnOffset 為 0 表示這個群組參照 C 資料欄，而偏移 1 則會參照 D 欄。
dataSourceColumnReference

object (DataSourceColumnReference)

這個分組依據的資料來源資料欄參照。

PivotGroupValueMetadata

資料透視分組中關於值的中繼資料。

JSON 表示法 
{
  "value": {
    object (ExtendedValue)
  },
  "collapsed": boolean
}
欄位
value

object (ExtendedValue)

中繼資料對應的計算值。(請注意，系統會計算 formulaValue 的值，因此無效)。
collapsed

boolean

如果對應該值的資料處於收合狀態，則為「true」。

PivotGroupSortValueBucket

瞭解資料透視表中哪些值應用於排序的相關資訊。

JSON 表示法 
{
  "valuesIndex": integer,
  "buckets": [
    {
      object (ExtendedValue)
    }
  ]
}
欄位
valuesIndex

integer

PivotTable.values 清單中的值做為排序依據的偏移值。
buckets[]

object (ExtendedValue)

決定系統會從哪個值區選擇要排序的值。

舉例來說，在含有 1 個資料列群組和兩個資料欄群組的資料透視表中，資料列群組最多可列出兩個值。第一個值對應至第一個資料欄群組中的一個值，第二個值則對應至第二個資料欄群組中的值。如果未列出任何值，則表示資料列應按照資料欄群組的「總和」排序。如果列出一個值，這就相當於使用該值區的「總計」值。

PivotGroupRule

PivotGroup 的選用設定，用來定義來源資料欄中值的範圍，而非細分每個值。來源資料中的每欄只能新增一個含有群組規則的 PivotGroup，不過在任何特定資料欄中，您都可以新增含有規則的 PivotGroup 和不含群組規則的 PivotGroup。

JSON 表示法 
{

  // Union field rule can be only one of the following:
  "manualRule": {
    object (ManualRule)
  },
  "histogramRule": {
    object (HistogramRule)
  },
  "dateTimeRule": {
    object (DateTimeRule)
  }
  // End of list of possible types for union field rule.
}
欄位
聯集欄位 rule。要套用至 PivotGroup 的規則。rule 只能採用下列其中一種設定：
manualRule

object (ManualRule)

ManualRule。
histogramRule

object (HistogramRule)

HistogramRule。
dateTimeRule

object (DateTimeRule)

DateTimeRule。

ManualRule

可讓您使用您選擇的名稱，手動將來源資料欄中的值歸類至值區。例如，依州別匯總人口資料的資料透視表：

+-------+-------------------+
| State | SUM of Population |
+-------+-------------------+
| AK    |               0.7 |
| AL    |               4.8 |
| AR    |               2.9 |
...
+-------+-------------------+

可以將群組清單 (例如 groupName = 'Central', items = ['AL', 'AR', 'IA', ...]) 列成手動的群組規則，即可轉換成依照時區匯總人口資料的資料透視表。請注意，只要在來源資料中加入時區欄，並調整資料透視表，即可達到類似的效果。 

+-----------+-------------------+
| Time Zone | SUM of Population |
+-----------+-------------------+
| Central   |             106.3 |
| Eastern   |             151.9 |
| Mountain  |              17.4 |
...
+-----------+-------------------+
JSON 表示法 
{
  "groups": [
    {
      object (ManualRuleGroup)
    }
  ]
}
欄位
groups[]

object (ManualRuleGroup)

群組名稱清單，以及來源資料中對應至各個群組名稱的對應項目。

ManualRuleGroup

來源資料中的群組名稱和項目清單，該資料應置於群組中。

JSON 表示法 
{
  "groupName": {
    object (ExtendedValue)
  },
  "items": [
    {
      object (ExtendedValue)
    }
  ]
}
欄位
groupName

object (ExtendedValue)

群組名稱，必須是字串。特定 ManualRule 中的每個群組都必須擁有專屬的群組名稱。
items[]

object (ExtendedValue)

來源資料中應放入這個群組的項目。每個項目可以是字串、數字或布林值。項目可能會出現在特定 ManualRule 的最多一個群組中。未出現在任何群組中的項目會自行顯示。

HistogramRule

可讓您將來源資料欄中的數字值整理成固定大小範圍的值區。HistogramRule.start 到 HistogramRule.end 之間的所有值會置於大小 HistogramRule.interval 的群組。此外，HistogramRule.start 底下的所有值都會放在一個群組中，超過 HistogramRule.end 的值則放在另一個群組中。只有 HistogramRule.interval 是必要項目，但如果同時提供 HistogramRule.start 和 HistogramRule.end，則 HistogramRule.start 必須小於 HistogramRule.end。舉例來說，資料透視表會依年齡顯示超過 50 列，並依年齡顯示平均購買金額： 

+-----+-------------------+
| Age | AVERAGE of Amount |
+-----+-------------------+
| 16  |            $27.13 |
| 17  |             $5.24 |
| 18  |            $20.15 |
...
+-----+-------------------+

套用 HistogramRule.start 為 25、HistogramRule.interval 為 20、HistogramRule.end 為 65 的直方圖群組規則，就能轉換成如下表所示的資料透視表。

+-------------+-------------------+
| Grouped Age | AVERAGE of Amount |
+-------------+-------------------+
| < 25        |            $19.34 |
| 25-45       |            $31.43 |
| 45-65       |            $35.87 |
| > 65        |            $27.55 |
+-------------+-------------------+
| Grand Total |            $29.12 |
+-------------+-------------------+
JSON 表示法 
{
  "interval": number,
  "start": number,
  "end": number
}
欄位
interval

number

建立的值區大小。必須為正數。
start

number

項目放置於固定大小區塊的最小值。下方的值會合併為單一範圍。這是選填欄位。

end

number

項目放置在常數大小區塊中的最大值。上方的值會形成單一特徵分塊。這是選填欄位。

DateTimeRule

允許您根據來源資料欄的日期時間值，根據標籤的日期或時間值選取的部分，將來源資料欄中的日期時間值整理成不同的值區。舉例來說，假設有一份資料透視表依日期顯示銷售交易： 

+----------+--------------+
| Date     | SUM of Sales |
+----------+--------------+
| 1/1/2017 |      $621.14 |
| 2/3/2017 |      $708.84 |
| 5/8/2017 |      $326.84 |
...
+----------+--------------+

套用 DateTimeRuleType 為 YEAR_MONTH 的日期時間群組規則時，系統會在以下資料透視表中產生結果。

+--------------+--------------+
| Grouped Date | SUM of Sales |
+--------------+--------------+
| 2017-Jan     |   $53,731.78 |
| 2017-Feb     |   $83,475.32 |
| 2017-Mar     |   $94,385.05 |
...
+--------------+--------------+
JSON 表示法 
{
  "type": enum (DateTimeRuleType)
}
欄位
type

enum (DateTimeRuleType)

要套用的日期時間分組類型。

DateTimeRuleType

可用的日期時間分組規則類型。本文件假設試算表的語言代碼是「en-US」，但某些規則類型的實際顯示日期和時間會採用試算表的語言代碼。

列舉
DATE_TIME_RULE_TYPE_UNSPECIFIED 預設類型不使用。
SECOND 將日期分組，範圍從 0 到 59。
MINUTE 以分鐘 (0 到 59) 為日期分組。
HOUR 使用 24 小時制 (0 到 23) 將日期分組。
HOUR_MINUTE 使用 24 小時系統按小時和分鐘將日期分組，例如 19:45。
HOUR_MINUTE_AMPM 使用 12 小時的系統，按小時和分鐘將日期分組，例如下午 7:45。系統會根據試算表語言代碼翻譯上午/下午標示。
DAY_OF_WEEK 依星期幾分組日期，例如星期日。系統會根據試算表語言代碼翻譯星期幾。
DAY_OF_YEAR 按星期幾 (1 到 366) 分組日期。請注意，2 月 29 日之後的日期與非閏年不同。
DAY_OF_MONTH 按月份 (1 到 31) 分組日期。
DAY_MONTH 依日期和月份分組日期，例如 22 至 11 月。系統會根據試算表語言代碼翻譯月份。
MONTH 按月分組日期，例如 11 月。系統會根據試算表語言代碼翻譯月份。
QUARTER 按季分組日期，例如 Q1 (代表 1 月至 3 月)。
YEAR 按年份分組日期，例如 2008。
YEAR_MONTH 依年份和月份分組日期，例如 2008 至 11 月。系統會根據試算表語言代碼翻譯月份。
YEAR_QUARTER 按年和季度分組日期，例如 2008 年第 4 季。
YEAR_MONTH_DAY 依照年、月和日分組日期，例如 2008-11-22。

PivotGroupLimit

資料透視表中資料列或資料欄的數量上限。

JSON 表示法 
{
  "countLimit": integer,
  "applyOrder": integer
}
欄位
countLimit

integer

數量限制。
applyOrder

integer

資料透視表套用群組限制的順序。

資料透視群組限制則由低至高套用。訂單編號會標準化為介於 0 的連續整數。

針對寫入要求，如要完整自訂套用順序，所有資料透視群組限制都必須將此欄位設為不重複的數字。否則，順序是由 PivotTable.rows 清單中的索引，然後是 PivotTable.columns 清單中的索引決定。

PivotFilterCriteria

在資料透視表中顯示/隱藏資料列的條件。

JSON 表示法 
{
  "visibleValues": [
    string
  ],
  "condition": {
    object (BooleanCondition)
  },
  "visibleByDefault": boolean
}
欄位
visibleValues[]

string

應加入的值。系統會排除這裡未列出的值。
condition

object (BooleanCondition)

值必須符合條件才會顯示。(visibleValues 不會覆寫此設定，即使其中有列出的值，不符合條件時仍會隱藏。)

參照 A1 標記法範圍的條件值會根據資料透視表工作表進行評估。參照項目是絕對的，因此不會在資料透視表下方填入。舉例來說，系統會將「資料透視表 1」中設為 =A1 的條件值視為 'Pivot Table 1'!$A$1。

您可以用欄標題名稱參照資料透視表的來源資料。舉例來說，假設來源資料包含「收益」和「費用」欄，且條件已套用至「收益」欄 (類型為「NUMBER_GREATER」且值是 =Cost)，那麼只有納入「收益」>「費用」的資料欄。
visibleByDefault

boolean

值是否預設為顯示。如為 True，系統會忽略 visibleValues，且會顯示所有符合 condition 的值 (如有指定)。如果設為 False，系統會顯示 visibleValues 中且符合 condition 的值。

PivotFilterSpec

與特定來源資料欄偏移相關的資料透視表篩選條件。

JSON 表示法 
{
  "filterCriteria": {
    object (PivotFilterCriteria)
  },

  // Union field source can be only one of the following:
  "columnOffsetIndex": integer,
  "dataSourceColumnReference": {
    object (DataSourceColumnReference)
  }
  // End of list of possible types for union field source.
}
欄位
filterCriteria

object (PivotFilterCriteria)

資料欄的條件。

聯集欄位 source。這個篩選器要套用的來源資料欄。source 只能採用下列其中一種設定：
columnOffsetIndex

integer

來源範圍的零資料欄偏移值。

dataSourceColumnReference

object (DataSourceColumnReference)

資料來源資料欄的參照。

PivotValue

定義資料透視表中值的計算方式。

JSON 表示法 
{
  "summarizeFunction": enum (PivotValueSummarizeFunction),
  "name": string,
  "calculatedDisplayType": enum (PivotValueCalculatedDisplayType),

  // Union field value can be only one of the following:
  "sourceColumnOffset": integer,
  "formula": string,
  "dataSourceColumnReference": {
    object (DataSourceColumnReference)
  }
  // End of list of possible types for union field value.
}
欄位
summarizeFunction

enum (PivotValueSummarizeFunction)

用於匯總值的函式。如果已設定 formula，唯一支援的值為 SUM 和 CUSTOM。如果已設定 sourceColumnOffset，則系統不支援 CUSTOM。
name

string

值要使用的名稱。
calculatedDisplayType

enum (PivotValueCalculatedDisplayType)

指定此選項時，表示資料透視值應在與其他資料透視值計算後顯示。例如，如果 computeDisplayType 指定為 PERCENT_OF_GRAND_TOTAL，則所有透視值都會顯示為總體總值的百分比。在 Google 試算表編輯器中，這項作業會在資料透視表的值部分顯示「顯示」。

聯集欄位 value。要在資料透視表中用於值的資料。只能設定一個值。value 只能採用下列其中一種設定：
sourceColumnOffset

integer

這個值讀取來源範圍的資料欄偏移值。

舉例來說，如果來源是 C10:E15，sourceColumnOffset 為 0 表示這個值參照 C 欄，而偏移 1 則會參照 D 欄。
formula

string

用於計算值的自訂公式。公式的開頭必須是 = 字元。
dataSourceColumnReference

object (DataSourceColumnReference)

這個值的參照資料來源欄。

PivotValueSummarizeFunction

用於匯總資料透視值的函式。

列舉
PIVOT_STANDARD_VALUE_FUNCTION_UNSPECIFIED 預設為不使用，
SUM 對應至 SUM 函式。
COUNTA 對應至 COUNTA 函式。
COUNT 對應至 COUNT 函式。
COUNTUNIQUE 對應至 COUNTUNIQUE 函式。
AVERAGE 對應至 AVERAGE 函式。
MAX 對應至 MAX 函式。
MIN 對應至 MIN 函式。
MEDIAN 對應至 MEDIAN 函式。
PRODUCT 對應至 PRODUCT 函式。
STDEV 對應至 STDEV 函式。
STDEVP 對應至 STDEVP 函式。
VAR 對應至 VAR 函式。
VARP 對應至 VARP 函式。
CUSTOM 表示應依原樣使用公式。只有在已設定 PivotValue.formula 的情況下才有效。
NONE 表示該值已匯總，且未明確指定摘要函式。適用於已匯總值摘要的 Looker 資料來源資料透視表。

PivotValueCalculatedDisplayType

為顯示資料計算資料透視值的可能原因。

列舉
PIVOT_VALUE_CALCULATED_DISPLAY_TYPE_UNSPECIFIED 預設值，請勿使用。
PERCENT_OF_ROW_TOTAL 呈現資料透視值在資料列總值中所佔的百分比。
PERCENT_OF_COLUMN_TOTAL 呈現資料透視值在資料欄總值中所佔的百分比。
PERCENT_OF_GRAND_TOTAL 呈現資料透視值在總值總值中所佔的百分比。

PivotValueLayout

資料透視值的版面配置。

列舉
HORIZONTAL 值會水平排列 (以欄為單位)。
VERTICAL 值會垂直排列 (以列形式顯示)。