|
| 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 | +//! Object Store abstracts access to an underlying file/object storage. |
| 19 | +
|
| 20 | +pub mod local; |
| 21 | + |
| 22 | +use std::collections::HashMap; |
| 23 | +use std::fmt::Debug; |
| 24 | +use std::pin::Pin; |
| 25 | +use std::sync::{Arc, RwLock}; |
| 26 | + |
| 27 | +use async_trait::async_trait; |
| 28 | +use futures::{AsyncRead, Stream}; |
| 29 | + |
| 30 | +use local::LocalFileSystem; |
| 31 | + |
| 32 | +use crate::error::{DataFusionError, Result}; |
| 33 | +use chrono::Utc; |
| 34 | + |
| 35 | +/// Object Reader for one file in a object store |
| 36 | +#[async_trait] |
| 37 | +pub trait ObjectReader { |
| 38 | + /// Get reader for a part [start, start + length] in the file asynchronously |
| 39 | + async fn chunk_reader(&self, start: u64, length: usize) |
| 40 | + -> Result<Arc<dyn AsyncRead>>; |
| 41 | + |
| 42 | + /// Get length for the file |
| 43 | + fn length(&self) -> u64; |
| 44 | +} |
| 45 | + |
| 46 | +/// Represents a file or a prefix that may require further resolution |
| 47 | +#[derive(Debug)] |
| 48 | +pub enum ListEntry { |
| 49 | + /// File metadata |
| 50 | + FileMeta(FileMeta), |
| 51 | + /// Prefix to be further resolved during partition discovery |
| 52 | + Prefix(String), |
| 53 | +} |
| 54 | + |
| 55 | +/// File meta we got from object store |
| 56 | +#[derive(Debug)] |
| 57 | +pub struct FileMeta { |
| 58 | + /// Path of the file |
| 59 | + pub path: String, |
| 60 | + /// Last time the file was modified in UTC |
| 61 | + pub last_modified: Option<chrono::DateTime<Utc>>, |
| 62 | + /// File size in total |
| 63 | + pub size: u64, |
| 64 | +} |
| 65 | + |
| 66 | +/// Stream of files get listed from object store |
| 67 | +pub type FileMetaStream = |
| 68 | + Pin<Box<dyn Stream<Item = Result<FileMeta>> + Send + Sync + 'static>>; |
| 69 | + |
| 70 | +/// Stream of list entries get from object store |
| 71 | +pub type ListEntryStream = |
| 72 | + Pin<Box<dyn Stream<Item = Result<ListEntry>> + Send + Sync + 'static>>; |
| 73 | + |
| 74 | +/// A ObjectStore abstracts access to an underlying file/object storage. |
| 75 | +/// It maps strings (e.g. URLs, filesystem paths, etc) to sources of bytes |
| 76 | +#[async_trait] |
| 77 | +pub trait ObjectStore: Sync + Send + Debug { |
| 78 | + /// Returns all the files in path `prefix` |
| 79 | + async fn list_file(&self, prefix: &str) -> Result<FileMetaStream>; |
| 80 | + |
| 81 | + /// Returns all the files in `prefix` if the `prefix` is already a leaf dir, |
| 82 | + /// or all paths between the `prefix` and the first occurrence of the `delimiter` if it is provided. |
| 83 | + async fn list_dir( |
| 84 | + &self, |
| 85 | + prefix: &str, |
| 86 | + delimiter: Option<String>, |
| 87 | + ) -> Result<ListEntryStream>; |
| 88 | + |
| 89 | + /// Get object reader for one file |
| 90 | + fn file_reader(&self, file: FileMeta) -> Result<Arc<dyn ObjectReader>>; |
| 91 | +} |
| 92 | + |
| 93 | +static LOCAL_SCHEME: &str = "file"; |
| 94 | + |
| 95 | +/// A Registry holds all the object stores at runtime with a scheme for each store. |
| 96 | +/// This allows the user to extend DataFusion with different storage systems such as S3 or HDFS |
| 97 | +/// and query data inside these systems. |
| 98 | +pub struct ObjectStoreRegistry { |
| 99 | + /// A map from scheme to object store that serve list / read operations for the store |
| 100 | + pub object_stores: RwLock<HashMap<String, Arc<dyn ObjectStore>>>, |
| 101 | +} |
| 102 | + |
| 103 | +impl ObjectStoreRegistry { |
| 104 | + /// Create the registry that object stores can registered into. |
| 105 | + /// ['LocalFileSystem'] store is registered in by default to support read local files natively. |
| 106 | + pub fn new() -> Self { |
| 107 | + let mut map: HashMap<String, Arc<dyn ObjectStore>> = HashMap::new(); |
| 108 | + map.insert(LOCAL_SCHEME.to_string(), Arc::new(LocalFileSystem)); |
| 109 | + |
| 110 | + Self { |
| 111 | + object_stores: RwLock::new(map), |
| 112 | + } |
| 113 | + } |
| 114 | + |
| 115 | + /// Adds a new store to this registry. |
| 116 | + /// If a store of the same prefix existed before, it is replaced in the registry and returned. |
| 117 | + pub fn register_store( |
| 118 | + &self, |
| 119 | + scheme: String, |
| 120 | + store: Arc<dyn ObjectStore>, |
| 121 | + ) -> Option<Arc<dyn ObjectStore>> { |
| 122 | + let mut stores = self.object_stores.write().unwrap(); |
| 123 | + stores.insert(scheme, store) |
| 124 | + } |
| 125 | + |
| 126 | + /// Get the store registered for scheme |
| 127 | + pub fn get(&self, scheme: &str) -> Option<Arc<dyn ObjectStore>> { |
| 128 | + let stores = self.object_stores.read().unwrap(); |
| 129 | + stores.get(scheme).cloned() |
| 130 | + } |
| 131 | + |
| 132 | + /// Get a suitable store for the URI based on it's scheme. For example: |
| 133 | + /// URI with scheme file or no schema will return the default LocalFS store, |
| 134 | + /// URI with scheme s3 will return the S3 store if it's registered. |
| 135 | + pub fn get_by_uri(&self, uri: &str) -> Result<Arc<dyn ObjectStore>> { |
| 136 | + if let Some((scheme, _)) = uri.split_once(':') { |
| 137 | + let stores = self.object_stores.read().unwrap(); |
| 138 | + stores |
| 139 | + .get(&*scheme.to_lowercase()) |
| 140 | + .map(Clone::clone) |
| 141 | + .ok_or_else(|| { |
| 142 | + DataFusionError::Internal(format!( |
| 143 | + "No suitable object store found for {}", |
| 144 | + scheme |
| 145 | + )) |
| 146 | + }) |
| 147 | + } else { |
| 148 | + Ok(Arc::new(LocalFileSystem)) |
| 149 | + } |
| 150 | + } |
| 151 | +} |
0 commit comments