object_store/
list.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18//! Paginated Listing
19
20use super::Result;
21use crate::ListResult;
22use async_trait::async_trait;
23use std::borrow::Cow;
24
25/// Options for a paginated list request
26#[derive(Debug, Default, Clone)]
27pub struct PaginatedListOptions {
28    /// Path to start listing from
29    ///
30    /// Note: Not all stores support this
31    ///
32    /// For stores that do support this, the returned
33    /// result should not include the object with this key.
34    pub offset: Option<String>,
35
36    /// A delimiter use to group keys with a common prefix
37    ///
38    /// Note: Some stores only support `/`
39    pub delimiter: Option<Cow<'static, str>>,
40
41    /// The maximum number of paths to return
42    pub max_keys: Option<usize>,
43
44    /// A page token from a previous request
45    ///
46    /// Note: Behaviour is implementation defined if the previous request
47    /// used a different prefix or options
48    pub page_token: Option<String>,
49
50    /// Implementation-specific extensions. Intended for use by implementations
51    /// that need to pass context-specific information (like tracing spans) via trait methods.
52    ///
53    /// These extensions are ignored entirely by backends offered through this crate.
54    pub extensions: http::Extensions,
55}
56
57/// A [`ListResult`] with optional pagination token
58#[derive(Debug)]
59pub struct PaginatedListResult {
60    /// The list result
61    pub result: ListResult,
62    /// If result set truncated, the pagination token to fetch next results
63    pub page_token: Option<String>,
64}
65
66/// A low-level interface for interacting with paginated listing APIs
67///
68/// Most use-cases should prefer [`ObjectStore::list`] as this is supported by more
69/// backends, including [`LocalFileSystem`], however, [`PaginatedListStore`] can be
70/// used where stateless pagination or non-path segment based listing is required
71///
72/// [`ObjectStore::list`]: crate::ObjectStore::list
73/// [`LocalFileSystem`]: crate::local::LocalFileSystem
74#[async_trait]
75pub trait PaginatedListStore: Send + Sync + 'static {
76    /// Perform a paginated list request
77    ///
78    /// Note: the order of returned objects is not guaranteed and
79    /// unlike [`ObjectStore::list`] a trailing delimiter is not
80    /// automatically added to `prefix`
81    ///
82    /// [`ObjectStore::list`]: crate::ObjectStore::list
83    async fn list_paginated(
84        &self,
85        prefix: Option<&str>,
86        opts: PaginatedListOptions,
87    ) -> Result<PaginatedListResult>;
88}
object_store/list.rs

object_store/
list.rs
