query method

AsyncResult<PaginatedResponse<Page>, AppException> query(DatabaseId databaseId, { bool forceFetchRelationPages = false, Filter? filter, List<Sort> sorts = const [], bool cacheRelationPages = false, CursorPaginationStrategyParams? paginationParams, })

Queries a Notion database and returns its properties.

databaseId is the ID of the database to query. forceFetchRelationPages determines whether to resolve relation properties. When set to true, it automatically fetches the properties of related pages for any relation properties so they are readily available. Example usage:

final result = await useCase.fetchPageProperties('page_id');
result.fold(
  onSuccess: (properties) {
    // Accessing a text property
    final titleProperty = properties['Title'] as TextProperty?;
    print('Page title: ${titleProperty?.value}');

    // Accessing a number property
    final priceProperty = properties['Price'] as Number?;
    print('Price: ${priceProperty?.value}');

    // Accessing a date property
    final dueDateProperty = properties['Due Date'] as Date?;
    print('Due date: ${dueDateProperty?.value}');
  },
  onFailure: (error) => print('Error: $error'),
);

It is recommended to set forceFetchRelationPages to false if there are many related pages, as this can lead to a large number of API calls. In that case, it is recommended to resolve related pages manually as needed.

Example usage:

final result = await useCase.query('database_id', forceFetchRelationPages: true);

result.fold(
  onSuccess: (properties) {
    properties['related_pages'].first.value; // Access the value of the first related
  },
  onFailure: (error) => print('Error: $error'),
);

To resolve the related pages manually later:

  final result = await useCase.query('database_id');

  final properties = result.valueOrNull ?? [];
  final relation = properties['related_pages'].first as RelationProperty;
  await relation.valueDetails?.value.first.resolve(useCase); // Resolve

  relation.valueDetails?.value.first.value; // Access the value of the first related page

Implementation

///  Example usage:
/// ```dart
/// final result = await useCase.fetchPageProperties('page_id');
/// result.fold(
///   onSuccess: (properties) {
///     // Accessing a text property
///     final titleProperty = properties['Title'] as TextProperty?;
///     print('Page title: ${titleProperty?.value}');
///
///     // Accessing a number property
///     final priceProperty = properties['Price'] as Number?;
///     print('Price: ${priceProperty?.value}');
///
///     // Accessing a date property
///     final dueDateProperty = properties['Due Date'] as Date?;
///     print('Due date: ${dueDateProperty?.value}');
///   },
///   onFailure: (error) => print('Error: $error'),
/// );
/// ```
///
/// It is recommended to set [forceFetchRelationPages] to false if there are many
/// related pages, as this can lead to a large number of API calls. In that case, it
/// is recommended to resolve related pages manually as needed.
///
/// Example usage:
/// ```dart
/// final result = await useCase.query('database_id', forceFetchRelationPages: true);
///
/// result.fold(
///   onSuccess: (properties) {
///     properties['related_pages'].first.value; // Access the value of the first related
///   },
///   onFailure: (error) => print('Error: $error'),
/// );
/// ```
/// To resolve the related pages manually later:
/// ```dart
///   final result = await useCase.query('database_id');
///
///   final properties = result.valueOrNull ?? [];
///   final relation = properties['related_pages'].first as RelationProperty;
///   await relation.valueDetails?.value.first.resolve(useCase); // Resolve
///
///   relation.valueDetails?.value.first.value; // Access the value of the first related page
/// ```
AsyncResult<PaginatedResponse<Page>, AppException> query(
  DatabaseId databaseId, {
  bool forceFetchRelationPages = false,
  Filter? filter,
  List<Sort> sorts = const [],

  /// When set to true, it'll make the API call for that relation page once.
  /// For subsequent calls, it'll use the cached value.
  /// Cache is only one-pass and is destroyed after the method call.
  bool cacheRelationPages = false,
  CursorPaginationStrategyParams? paginationParams,
}) =>
    _useCase.query(
      databaseId,
      forceFetchRelationPages: forceFetchRelationPages,
      filter: filter,
      cacheRelationPages: cacheRelationPages,
      paginationParams: paginationParams,
      sorts: sorts,
    );