1 // Copyright (C) 2023 Google LLC 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef ICING_JOIN_QUALIFIED_ID_JOIN_INDEX_H_ 16 #define ICING_JOIN_QUALIFIED_ID_JOIN_INDEX_H_ 17 18 #include <cstdint> 19 #include <memory> 20 #include <string> 21 #include <string_view> 22 #include <utility> 23 #include <vector> 24 25 #include "icing/text_classifier/lib3/utils/base/status.h" 26 #include "icing/text_classifier/lib3/utils/base/statusor.h" 27 #include "icing/file/filesystem.h" 28 #include "icing/file/persistent-storage.h" 29 #include "icing/join/document-id-to-join-info.h" 30 #include "icing/join/document-join-id-pair.h" 31 #include "icing/schema/joinable-property.h" 32 #include "icing/store/document-filter-data.h" 33 #include "icing/store/document-id.h" 34 #include "icing/store/namespace-id-fingerprint.h" 35 #include "icing/store/namespace-id.h" 36 #include "icing/util/crc32.h" 37 38 namespace icing { 39 namespace lib { 40 41 // QualifiedIdJoinIndex: an abstract class to maintain data for qualified id 42 // joining. 43 class QualifiedIdJoinIndex : public PersistentStorage { 44 public: 45 class JoinDataIteratorBase { 46 public: 47 virtual ~JoinDataIteratorBase() = default; 48 49 virtual libtextclassifier3::Status Advance() = 0; 50 51 virtual const DocumentIdToJoinInfo<NamespaceIdFingerprint>& GetCurrent() 52 const = 0; 53 }; 54 55 enum class Version { kV2, kV3 }; 56 57 static constexpr WorkingPathType kWorkingPathType = 58 WorkingPathType::kDirectory; 59 60 // Deletes QualifiedIdJoinIndex under working_path. 61 // 62 // Returns: 63 // - OK on success 64 // - INTERNAL_ERROR on I/O error Discard(const Filesystem & filesystem,const std::string & working_path)65 static libtextclassifier3::Status Discard(const Filesystem& filesystem, 66 const std::string& working_path) { 67 return PersistentStorage::Discard(filesystem, working_path, 68 kWorkingPathType); 69 } 70 71 virtual ~QualifiedIdJoinIndex() override = default; 72 73 // (v2 only) Puts a list of referenced NamespaceIdFingerprint into index, 74 // given the DocumentId, SchemaTypeId and JoinablePropertyId. 75 // 76 // Returns: 77 // - OK on success 78 // - INVALID_ARGUMENT_ERROR if schema_type_id, joinable_property_id, or 79 // document_id is invalid 80 // - Any KeyMapper/FlashIndexStorage errors 81 virtual libtextclassifier3::Status Put( 82 SchemaTypeId schema_type_id, JoinablePropertyId joinable_property_id, 83 DocumentId document_id, 84 std::vector<NamespaceIdFingerprint>&& 85 ref_namespace_id_uri_fingerprints) = 0; 86 87 // (v3 only) Puts a new child document and its referenced parent documents 88 // into the join index. 89 // 90 // Returns: 91 // - OK on success 92 // - INVALID_ARGUMENT_ERROR if child_document_join_id_pair is invalid 93 // - Any FileBackedVector errors 94 virtual libtextclassifier3::Status Put( 95 const DocumentJoinIdPair& child_document_join_id_pair, 96 std::vector<DocumentId>&& parent_document_ids) = 0; 97 98 // (v2 only) Returns a JoinDataIterator for iterating through all join data of 99 // the specified (schema_type_id, joinable_property_id). 100 // 101 // Returns: 102 // - On success: a JoinDataIterator 103 // - INVALID_ARGUMENT_ERROR if schema_type_id or joinable_property_id is 104 // invalid 105 // - Any KeyMapper/FlashIndexStorage errors 106 virtual libtextclassifier3::StatusOr<std::unique_ptr<JoinDataIteratorBase>> 107 GetIterator(SchemaTypeId schema_type_id, 108 JoinablePropertyId joinable_property_id) const = 0; 109 110 // (v3 only) Gets the list of joinable children for the given parent document 111 // id. 112 // 113 // Returns: 114 // - A list of children's DocumentJoinIdPair on success 115 // - Any FileBackedVector errors 116 virtual libtextclassifier3::StatusOr<std::vector<DocumentJoinIdPair>> Get( 117 DocumentId parent_document_id) const = 0; 118 119 // Migrates existing join data for a parent document from old_document_id to 120 // new_document_id if necessary. 121 // 122 // Returns: 123 // - OK on success 124 // - INVALID_ARGUMENT_ERROR if any document id is invalid 125 // - Any errors, depending on the implementation 126 virtual libtextclassifier3::Status MigrateParent( 127 DocumentId old_document_id, DocumentId new_document_id) = 0; 128 129 // Reduces internal file sizes by reclaiming space and ids of deleted 130 // documents. Qualified id type joinable index will convert all entries to the 131 // new document ids. 132 // 133 // - document_id_old_to_new: a map for converting old document id to new 134 // document id. 135 // - namespace_id_old_to_new: a map for converting old namespace id to new 136 // namespace id. 137 // - new_last_added_document_id: will be used to update the last added 138 // document id in the qualified id type joinable 139 // index. 140 // 141 // Returns: 142 // - OK on success 143 // - INTERNAL_ERROR on I/O error. This could potentially leave the index in 144 // an invalid state and the caller should handle it properly (e.g. discard 145 // and rebuild) 146 virtual libtextclassifier3::Status Optimize( 147 const std::vector<DocumentId>& document_id_old_to_new, 148 const std::vector<NamespaceId>& namespace_id_old_to_new, 149 DocumentId new_last_added_document_id) = 0; 150 151 // Clears all data and set last_added_document_id to kInvalidDocumentId. 152 // 153 // Returns: 154 // - OK on success 155 // - INTERNAL_ERROR on I/O error 156 virtual libtextclassifier3::Status Clear() = 0; 157 158 virtual Version version() const = 0; 159 160 virtual int32_t size() const = 0; 161 162 virtual bool empty() const = 0; 163 164 virtual DocumentId last_added_document_id() const = 0; 165 166 virtual void set_last_added_document_id(DocumentId document_id) = 0; 167 168 protected: QualifiedIdJoinIndex(const Filesystem & filesystem,std::string && working_path)169 explicit QualifiedIdJoinIndex(const Filesystem& filesystem, 170 std::string&& working_path) 171 : PersistentStorage(filesystem, std::move(working_path), 172 kWorkingPathType) {} 173 174 virtual libtextclassifier3::Status PersistStoragesToDisk() override = 0; 175 176 virtual libtextclassifier3::Status PersistMetadataToDisk() override = 0; 177 178 virtual libtextclassifier3::StatusOr<Crc32> UpdateStoragesChecksum() 179 override = 0; 180 181 virtual libtextclassifier3::StatusOr<Crc32> GetInfoChecksum() 182 const override = 0; 183 184 virtual libtextclassifier3::StatusOr<Crc32> GetStoragesChecksum() 185 const override = 0; 186 187 virtual Crcs& crcs() override = 0; 188 virtual const Crcs& crcs() const override = 0; 189 }; 190 191 } // namespace lib 192 } // namespace icing 193 194 #endif // ICING_JOIN_QUALIFIED_ID_JOIN_INDEX_H_ 195