picked 0.0.101 → 0.0.102-next.2

package/docs/reference/management-api/schema/report.md

@@ -6,13 +6,14 @@ generated: true
 
 # Report schema
 
-The operations and types that `report.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
 
 ## Queries
 
 ### `report`
 
-Fetch a single report by id. Requires authentication.
+Reads a project report. Null when no project report has the ID.
+Scope: `ORGANIZATION_REPORTS_READ`.
 
 ```graphql
 report(id: ID!): ProjectReport @auth
@@ -22,7 +23,8 @@ report(id: ID!): ProjectReport @auth
 
 ### `reportCreate`
 
-Create a new report. Requires scope: `ORGANIZATION_REPORTS_CREATE`.
+Creates a report and adds it to a project.
+Scope: `ORGANIZATION_REPORTS_CREATE`.
 
 ```graphql
 reportCreate(input: ReportCreateInput!): ReportCreatePayload! @auth
@@ -30,7 +32,8 @@ reportCreate(input: ReportCreateInput!): ReportCreatePayload! @auth
 
 ### `reportUpdate`
 
-Update a report. Requires scope: `ORGANIZATION_REPORTS_UPDATE`.
+Updates a project report and its report.
+Scope: `ORGANIZATION_REPORTS_UPDATE`.
 
 ```graphql
 reportUpdate(input: ReportUpdateInput!): ReportUpdatePayload! @auth
@@ -38,7 +41,8 @@ reportUpdate(input: ReportUpdateInput!): ReportUpdatePayload! @auth
 
 ### `reportDelete`
 
-Delete a report. Requires scope: `ORGANIZATION_REPORTS_DELETE`.
+Deletes a report from its project, and the report itself when no other project uses it.
+Scope: `ORGANIZATION_REPORTS_DELETE`.
 
 ```graphql
 reportDelete(input: ReportDeleteInput!): ReportDeletePayload! @auth
@@ -49,15 +53,13 @@ reportDelete(input: ReportDeleteInput!): ReportDeletePayload! @auth
 ### `ReportSortKeys`
 
 ```graphql
-"""
-Sort keys accepted by `Project.reports(...)`. Pair with `reverse: true` to flip the order.
-"""
+"""The orders a report list can take. `reverse: true` flips the order."""
 enum ReportSortKeys {
-  """Sort by report `name` (alphabetical)."""
+  """By name, A to Z."""
   NAME
-  """Sort by display order (the manual order the user assigned)."""
+  """By display order, lowest first."""
   DISPLAY_ORDER
-  """Sort by `createdAt`."""
+  """By creation time, oldest first."""
   CREATED_AT
 }
 ```
@@ -65,11 +67,11 @@ enum ReportSortKeys {
 ### `ReportType`
 
 ```graphql
-"""Type of report (one chart vs. a dashboard of charts)."""
+"""What a Metabase report embeds."""
 enum ReportType {
-  """A single question / chart report."""
+  """One question, a single chart."""
   QUESTION
-  """A multi-chart dashboard report."""
+  """A dashboard of several charts."""
   DASHBOARD
 }
 ```
@@ -78,24 +80,22 @@ enum ReportType {
 
 ```graphql
 """
-Picked-side report definition — a pointer to a Metabase report
-(question or dashboard) plus the display-only metadata (name,
-description).
+An embedded analytics dashboard or question: a Metabase report with a name and description.
 """
 type Report {
-  """Unique identifier for the report."""
+  """The ID of the report."""
   id: ID!
-  """Metabase report id."""
+  """The ID of the Metabase question or dashboard."""
   metabaseReportId: Int!
-  """Display name of the report."""
+  """The name of the report."""
   name: String!
-  """Description of the report."""
+  """The description of the report. Null when it has none."""
   description: String
-  """Type of the Metabase report."""
+  """What the Metabase report embeds."""
   metabaseReportType: ReportType!
-  """When this report was created."""
+  """When the report was created."""
   createdAt: DateTime!
-  """When this report was last updated."""
+  """When the report last changed."""
   updatedAt: DateTime!
 }
 ```
@@ -104,24 +104,29 @@ type Report {
 
 ```graphql
 """
-A report assigned to a project with embed configuration. The
-`lockedParameters` blob is forwarded to Metabase when generating the
-embed URL — typically used to lock the report to the project's id.
+A report attached to a project, with the parameters its embed is locked to.
 """
 type ProjectReport {
-  """Unique identifier for the project report."""
+  """The ID of the project report."""
   id: ID!
-  """The underlying report definition."""
+  """The report."""
   report: Report!
-  """Parameters locked for the embedded report (forwarded to Metabase)."""
+  """
+  The Metabase parameters the embed is locked to, such as the project's ID. Null when none are
+  set.
+  """
   lockedParameters: JSON
-  """Display order in the project's report list. Null orders last."""
+  """The position of the report in the project's list. Null sorts last."""
   displayOrder: Int
-  """When this project report was created."""
+  """When the report was added to the project."""
   createdAt: DateTime!
-  """Email of the user who created this project report."""
+  """
+  The ID of the user who added the report to the project. Null when unknown.
+  """
   createdBy: String
-  """Embeddable URL for the report — sign and time-limited."""
+  """
+  A signed embed URL for the report. It expires 3 hours after it is read.
+  """
   embedUrl: String!
 }
 ```
@@ -129,9 +134,9 @@ type ProjectReport {
 ### `ProjectReportEdge`
 
 ```graphql
-"""Edge type for `ProjectReportConnection`."""
+"""A project report in a page of results."""
 type ProjectReportEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The project report."""
   node: ProjectReport!
@@ -141,13 +146,13 @@ type ProjectReportEdge {
 ### `ProjectReportConnection`
 
 ```graphql
-"""Relay-style connection of project reports."""
+"""A page of project reports."""
 type ProjectReportConnection {
-  """List of project-report edges."""
+  """The edges in this page."""
   edges: [ProjectReportEdge!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of project reports."""
+  """The total number of reports on the project."""
   totalCount: Int!
 }
 ```
@@ -155,23 +160,23 @@ type ProjectReportConnection {
 ### `ReportCreateInput`
 
 ```graphql
-"""Input for `reportCreate`."""
+"""The input of `reportCreate`."""
 input ReportCreateInput {
-  """ID of the project to add the report to."""
+  """The ID of the project to add the report to."""
   projectId: ID!
-  """ID of the organisation."""
+  """Ignored. The project's organisation applies."""
   organizationId: ID!
-  """Display name for the report."""
+  """The name of the report. Must not be blank."""
   name: String!
-  """Description of the report."""
+  """The description of the report."""
   description: String
-  """Metabase report id to embed."""
+  """The ID of the Metabase question or dashboard. Must be positive."""
   metabaseReportId: Int!
-  """Type of the Metabase report."""
+  """What the Metabase report embeds."""
   metabaseReportType: ReportType!
-  """Parameters to lock for the embedded report."""
+  """The Metabase parameters to lock the embed to. Defaults to none."""
   lockedParameters: JSON
-  """Display order in the project's report list."""
+  """The position of the report in the project's list."""
   displayOrder: Int
 }
 ```
@@ -179,7 +184,7 @@ input ReportCreateInput {
 ### `ReportCreatePayload`
 
 ```graphql
-"""Payload returned by `reportCreate`."""
+"""The result of `reportCreate`."""
 type ReportCreatePayload {
   """The created project report."""
   projectReport: ProjectReport
@@ -190,24 +195,23 @@ type ReportCreatePayload {
 
 ```graphql
 """
-Input for `reportUpdate`. Omit a field to leave it unchanged (except `metabaseReportType`, which is required).
+The input of `reportUpdate`. Omit a field to keep its value. Null clears `description` and
+`displayOrder`.
 """
 input ReportUpdateInput {
-  """ID of the project report to update."""
+  """The ID of the project report."""
   projectReportId: ID!
-  """New display name."""
+  """The name of the report."""
   name: String
-  """New description."""
+  """The description of the report."""
   description: String
-  """New Metabase report id."""
+  """The ID of the Metabase question or dashboard."""
   metabaseReportId: Int
-  """
-  Type of the Metabase report. Required to disambiguate `metabaseReportId`.
-  """
+  """What the Metabase report embeds. Required."""
   metabaseReportType: ReportType!
-  """New locked parameters."""
+  """The Metabase parameters to lock the embed to."""
   lockedParameters: JSON
-  """New display order."""
+  """The position of the report in the project's list."""
   displayOrder: Int
 }
 ```
@@ -215,7 +219,7 @@ input ReportUpdateInput {
 ### `ReportUpdatePayload`
 
 ```graphql
-"""Payload returned by `reportUpdate`."""
+"""The result of `reportUpdate`."""
 type ReportUpdatePayload {
   """The updated project report."""
   projectReport: ProjectReport
@@ -225,9 +229,9 @@ type ReportUpdatePayload {
 ### `ReportDeleteInput`
 
 ```graphql
-"""Input for `reportDelete`."""
+"""The input of `reportDelete`."""
 input ReportDeleteInput {
-  """ID of the project report to delete."""
+  """The ID of the project report."""
   projectReportId: ID!
 }
 ```
@@ -235,9 +239,9 @@ input ReportDeleteInput {
 ### `ReportDeletePayload`
 
 ```graphql
-"""Payload returned by `reportDelete`."""
+"""The result of `reportDelete`."""
 type ReportDeletePayload {
-  """Whether the report was deleted successfully."""
+  """Whether the report was deleted."""
   success: Boolean!
 }
 ```

package/docs/reference/management-api/schema/saved-view.md

@@ -6,13 +6,14 @@ generated: true
 
 # Saved view schema
 
-The operations and types that `saved-view.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
 
 ## Queries
 
 ### `savedView`
 
-Get a saved view by ID. Requires scope: `ORGANIZATION_PROJECTS_READ`.
+Reads a saved view.
+Scope: `ORGANIZATION_PROJECTS_READ`.
 
 ```graphql
 savedView(input: SavedViewInput!): SavedView @auth
@@ -22,7 +23,8 @@ savedView(input: SavedViewInput!): SavedView @auth
 
 ### `savedViewCreate`
 
-Save a view of a project's list. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Creates a saved view of a list in a project.
+Scope: `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 savedViewCreate(input: SavedViewCreateInput!): SavedViewCreatePayload! @auth
@@ -30,7 +32,8 @@ savedViewCreate(input: SavedViewCreateInput!): SavedViewCreatePayload! @auth
 
 ### `savedViewUpdate`
 
-Rename a saved view, change what it restores, or move the default. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Updates a saved view: its name, its controls, or whether it is the default.
+Scope: `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 savedViewUpdate(input: SavedViewUpdateInput!): SavedViewUpdatePayload! @auth
@@ -38,7 +41,8 @@ savedViewUpdate(input: SavedViewUpdateInput!): SavedViewUpdatePayload! @auth
 
 ### `savedViewDelete`
 
-Delete a saved view. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Deletes a saved view.
+Scope: `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 savedViewDelete(input: SavedViewDeleteInput!): SavedViewDeletePayload! @auth
@@ -49,19 +53,19 @@ savedViewDelete(input: SavedViewDeleteInput!): SavedViewDeletePayload! @auth
 ### `SavedView`
 
 ```graphql
-"""A named set of list controls, restoring what a list page looked like."""
+"""
+A named set of controls for a list page in the dashboard, shared by everyone on the project.
+"""
 type SavedView {
-  """Unique saved view identifier."""
+  """The ID of the saved view."""
   id: ID!
-  """ID of the project this view belongs to."""
+  """The ID of the project the saved view belongs to."""
   projectId: ID!
-  """Which list this view applies to."""
+  """The list the saved view applies to."""
   resource: SavedViewResource!
-  """What the viewer called it."""
+  """The name of the saved view."""
   name: String!
-  """
-  The `q` query-string value: the list's own search language, uninterpreted.
-  """
+  """The `q` query-string value: a search in the list's query language."""
   query: String
   """
   The `cols` query-string value: comma-separated column paths, in display order.
@@ -78,34 +82,31 @@ type SavedView {
   """
   windowTo: String
   """
-  The `last` query-string value: how many units a relative capture window spans.
+  The `last` query-string value: the number of units a relative capture window spans.
   """
   windowLast: String
-  """
-  The `unit` query-string value: the unit a relative capture window counts in.
-  """
+  """The `unit` query-string value: the unit of a relative capture window."""
   windowUnit: String
-  """The `chart` query-string value: how the chart above the list is drawn."""
+  """The `chart` query-string value: the kind of chart above the list."""
   chart: String
-  """
-  The `interval` query-string value: the bucket width of the chart above the list.
-  """
+  """The `interval` query-string value: the bucket width of the chart."""
   chartInterval: String
   """
-  The `chartBy` query-string value: the path the chart above the list splits its series by.
+  The `chartBy` query-string value: the path that splits the chart into series.
   """
   chartBy: String
   """
-  The `compare` query-string value: `previous` when the chart above the list outlines the period before its window.
+  The `compare` query-string value: `previous` when the chart shows the period before its window.
   """
   chartCompare: String
   """
-  Whether entering the list with nothing in its URL opens this view. At most one per project and resource.
+  Whether the list opens with this view when its URL has no controls. At most one per project and
+  list.
   """
   isDefault: Boolean!
-  """When this view was saved."""
+  """When the saved view was created."""
   createdAt: DateTime!
-  """When this view was last changed."""
+  """When the saved view last changed."""
   updatedAt: DateTime!
 }
 ```
@@ -115,9 +116,9 @@ type SavedView {
 ```graphql
 """The list a saved view applies to."""
 enum SavedViewResource {
-  """The project's captured leads."""
+  """The leads of the project."""
   LEADS
-  """The project's visitor sessions, read from its analytics warehouse."""
+  """The visits to the project."""
   SESSIONS
 }
 ```
@@ -125,17 +126,15 @@ enum SavedViewResource {
 ### `SavedViewConnection`
 
 ```graphql
-"""Relay-style connection of saved views."""
+"""A page of saved views."""
 type SavedViewConnection {
-  """List of saved view edges."""
+  """The edges in this page."""
   edges: [SavedViewEdge!]!
-  """
-  Flat list of saved views, equivalent to `edges[].node`. Convenience accessor.
-  """
+  """The saved views in this page."""
   nodes: [SavedView!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of saved views matching the query."""
+  """The total number of saved views."""
   totalCount: Int!
 }
 ```
@@ -143,9 +142,9 @@ type SavedViewConnection {
 ### `SavedViewEdge`
 
 ```graphql
-"""Edge type for `SavedViewConnection`."""
+"""A saved view in a page of results."""
 type SavedViewEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The saved view."""
   node: SavedView!
@@ -155,9 +154,9 @@ type SavedViewEdge {
 ### `SavedViewInput`
 
 ```graphql
-"""Input for the top-level `savedView` query."""
+"""The input of `savedView`."""
 input SavedViewInput {
-  """ID of the saved view to fetch."""
+  """The ID of the saved view."""
   id: ID!
 }
 ```
@@ -165,13 +164,13 @@ input SavedViewInput {
 ### `SavedViewCreateInput`
 
 ```graphql
-"""Input for `savedViewCreate`."""
+"""The input of `savedViewCreate`."""
 input SavedViewCreateInput {
-  """ID of the project the view belongs to."""
+  """The ID of the project."""
   projectId: ID!
-  """Which list this view applies to."""
+  """The list the saved view applies to."""
   resource: SavedViewResource!
-  """What to call it. One to 120 characters once trimmed."""
+  """The name: 1 to 120 characters after trimming."""
   name: String!
   """The `q` query-string value."""
   query: String
@@ -196,7 +195,7 @@ input SavedViewCreateInput {
   """The `compare` query-string value."""
   chartCompare: String
   """
-  Make this the view the list opens with. Takes the default from whichever view held it.
+  Whether to make this the default view, taking the default from the view that held it.
   """
   isDefault: Boolean
 }
@@ -206,37 +205,38 @@ input SavedViewCreateInput {
 
 ```graphql
 """
-Input for `savedViewUpdate`. An omitted field is left as it is, so renaming a
-view does not disturb the URL it restores.
+The input of `savedViewUpdate`. Omit a field to keep its value. Null clears a query-string value.
 """
 input SavedViewUpdateInput {
-  """ID of the saved view to update."""
+  """The ID of the saved view."""
   id: ID!
-  """A new name."""
+  """The name: 1 to 120 characters after trimming."""
   name: String
-  """A new `q` query-string value."""
+  """The `q` query-string value."""
   query: String
-  """A new `cols` query-string value."""
+  """The `cols` query-string value."""
   columnPaths: String
-  """A new `sort` query-string value."""
+  """The `sort` query-string value."""
   sort: String
-  """A new `from` query-string value."""
+  """The `from` query-string value."""
   windowFrom: String
-  """A new `to` query-string value."""
+  """The `to` query-string value."""
   windowTo: String
-  """A new `last` query-string value."""
+  """The `last` query-string value."""
   windowLast: String
-  """A new `unit` query-string value."""
+  """The `unit` query-string value."""
   windowUnit: String
-  """A new `chart` query-string value."""
+  """The `chart` query-string value."""
   chart: String
-  """A new `interval` query-string value."""
+  """The `interval` query-string value."""
   chartInterval: String
-  """A new `chartBy` query-string value."""
+  """The `chartBy` query-string value."""
   chartBy: String
-  """A new `compare` query-string value."""
+  """The `compare` query-string value."""
   chartCompare: String
-  """Take or give up the default."""
+  """
+  Whether this is the default view. True takes the default from the view that held it.
+  """
   isDefault: Boolean
 }
 ```
@@ -244,9 +244,9 @@ input SavedViewUpdateInput {
 ### `SavedViewDeleteInput`
 
 ```graphql
-"""Input for `savedViewDelete`."""
+"""The input of `savedViewDelete`."""
 input SavedViewDeleteInput {
-  """ID of the saved view to delete."""
+  """The ID of the saved view."""
   id: ID!
 }
 ```
@@ -254,11 +254,11 @@ input SavedViewDeleteInput {
 ### `SavedViewCreatePayload`
 
 ```graphql
-"""Payload returned by `savedViewCreate`."""
+"""The result of `savedViewCreate`."""
 type SavedViewCreatePayload {
-  """The saved view, or null when `userErrors` is non-empty."""
+  """The saved view."""
   savedView: SavedView
-  """Validation failures, keyed by input field."""
+  """The errors. Always empty: an invalid input fails with a GraphQL error."""
   userErrors: [UserError!]!
 }
 ```
@@ -266,11 +266,11 @@ type SavedViewCreatePayload {
 ### `SavedViewUpdatePayload`
 
 ```graphql
-"""Payload returned by `savedViewUpdate`."""
+"""The result of `savedViewUpdate`."""
 type SavedViewUpdatePayload {
-  """The updated saved view, or null when `userErrors` is non-empty."""
+  """The saved view."""
   savedView: SavedView
-  """Validation failures, keyed by input field."""
+  """The errors. Always empty: an invalid input fails with a GraphQL error."""
   userErrors: [UserError!]!
 }
 ```
@@ -278,11 +278,11 @@ type SavedViewUpdatePayload {
 ### `SavedViewDeletePayload`
 
 ```graphql
-"""Payload returned by `savedViewDelete`."""
+"""The result of `savedViewDelete`."""
 type SavedViewDeletePayload {
-  """ID of the deleted saved view."""
+  """The ID of the deleted saved view."""
   deletedSavedViewId: ID
-  """Validation failures, keyed by input field."""
+  """The errors. Always empty."""
   userErrors: [UserError!]!
 }
 ```