file2document_service.py

Overview

file2document_service.py defines the File2DocumentService class, which provides database service methods managing the relationships between files and documents within the InfiniFlow application. It acts as a specialized service layer to perform CRUD (Create, Read, Update, Delete) operations on the File2Document model, which represents the many-to-many or associative relationship between File and Document entities.

This service abstracts direct database access and offers utility methods to query, insert, update, and delete file-document linkage records, as well as retrieving storage locations related to files or documents.

Classes and Methods

Class: File2DocumentService

File2DocumentService extends CommonService and operates primarily on the File2Document database model. It uses decorators to ensure all database operations run within a proper database connection context (@DB.connection_context()).

Attributes

• model (File2Document): The database model this service operates on.

Methods

get_by_file_id(file_id)

• Type: Class Method

• Parameters:

  • file_id (int): The ID of the file to query associations for.

• Returns: A query result (iterable) of File2Document instances linked to the given file ID.

• Description: Retrieves all File2Document entries where the file_id matches the provided ID.

• Usage Example:

  file_links = File2DocumentService.get_by_file_id(123)
  for link in file_links:
      print(link.document_id)
  

get_by_document_id(document_id)

• Type: Class Method

• Parameters:

  • document_id (int): The ID of the document to query associations for.

• Returns: A query result (iterable) of File2Document instances linked to the given document ID.

• Description: Retrieves all File2Document entries where the document_id matches the provided ID.

• Usage Example:

  document_links = File2DocumentService.get_by_document_id(456)
  for link in document_links:
      print(link.file_id)
  

insert(obj)

• Type: Class Method

• Parameters:

  • obj (dict): A dictionary representing the attributes of a new File2Document record to insert.

• Returns: An instance of File2Document representing the newly inserted record.

• Raises: RuntimeError if the database save operation fails.

• Description: Attempts to insert a new file-document association record into the database.

• Usage Example:

  new_link = File2DocumentService.insert({
      "file_id": 123,
      "document_id": 456,
      "create_time": current_timestamp(),
      "update_time": current_timestamp(),
  })
  

delete_by_file_id(file_id)

• Type: Class Method

• Parameters:

  • file_id (int): The ID of the file whose associations should be deleted.

• Returns: The number of rows deleted (int).

• Description: Deletes all File2Document entries linked to the specified file ID.

• Usage Example:

  deleted_count = File2DocumentService.delete_by_file_id(123)
  print(f"Deleted {deleted_count} associations.")
  

delete_by_document_id(doc_id)

• Type: Class Method

• Parameters:

  • doc_id (int): The ID of the document whose associations should be deleted.

• Returns: The number of rows deleted (int).

• Description: Deletes all File2Document entries linked to the specified document ID.

• Usage Example:

  deleted_count = File2DocumentService.delete_by_document_id(456)
  print(f"Deleted {deleted_count} associations.")
  

update_by_file_id(file_id, obj)

• Type: Class Method

• Parameters:

  • file_id (int): The ID of the file whose association record to update.

  • obj (dict): A dictionary containing the fields and values to update.

• Returns: An updated File2Document instance reflecting the changes.

• Description: Updates the record associated with the given file_id with new data, also updates the update_time and update_date fields to the current time.

• Usage Example:

  updated_link = File2DocumentService.update_by_file_id(123, {
      "document_id": 789,
      # other fields as needed
  })
  

• Implementation Detail:
  The method sets update_time to the current timestamp and update_date to a formatted datetime string before performing the update.

get_storage_address(doc_id=None, file_id=None)

• Type: Class Method

• Parameters:

  • doc_id (int, optional): Document ID to find the storage address for.

  • file_id (int, optional): File ID to find the storage address for.

• Returns: A tuple (parent_id, location) for file storage or (kb_id, location) for document storage.

• Description: Retrieves the storage location associated with either a file or document by:

  • Querying File2Document by document ID or file ID.

  • Fetching the corresponding File or Document record.

  • Returning the appropriate storage identifiers depending on whether the file source is local or not.

• Usage Example:

  parent_id, location = File2DocumentService.get_storage_address(file_id=123)
  kb_id, location = File2DocumentService.get_storage_address(doc_id=456)
  

• Important Logic:

  • If doc_id is provided, the method gets the linkage by document; otherwise, by file ID.

  • If the file's source_type is local or not specified, it returns the file's parent_id and location.

  • If not local, it retrieves the document's kb_id (knowledge base ID) and location.

  • Raises an assertion error if neither doc_id nor valid linkage is found.

Important Implementation Details

• Database Context Management:
  Every method that interacts with the database is wrapped with the @DB.connection_context() decorator, ensuring that database connections are properly opened and closed for each operation.

• Model Abstraction:
  The service operates on the File2Document ORM model, encapsulating raw database queries and updates behind class methods. This improves modularity and testability.

• Timestamp Handling:
  The update method uses utility functions current_timestamp() and datetime_format() to maintain consistent timestamp formats in the database records.

• Error Handling:
  The insert method explicitly checks for save success and raises a RuntimeError if the insertion fails, signaling higher layers of potential database issues.

Interaction With Other Components

• Database Models:

  • File2Document — Primary model representing file-document associations.

  • File — Used to fetch file metadata and location.

  • Document — Accessed through DocumentService to retrieve document-related storage info.

• Services:

  • CommonService — Base class providing common database service functionality.

  • DocumentService — Used to fetch document details when resolving storage addresses.

• Utilities:

  • current_timestamp and datetime_format — Utility functions to manage timestamps.

• Database Connection:

  • DB — Database context manager ensuring safe and consistent database connections.

This service acts as a middle layer between the database layer and higher application logic that needs to manage or query file-document relationships and their storage locations.

Mermaid Class Diagram

classDiagram
    class File2DocumentService {
        <<Service>>
        +model: File2Document
        +get_by_file_id(file_id)
        +get_by_document_id(document_id)
        +insert(obj)
        +delete_by_file_id(file_id)
        +delete_by_document_id(doc_id)
        +update_by_file_id(file_id, obj)
        +get_storage_address(doc_id=None, file_id=None)
    }

    File2DocumentService --|> CommonService
    File2DocumentService ..> File2Document : uses
    File2DocumentService ..> File : queries
    File2DocumentService ..> DocumentService : interacts

Summary

The File2DocumentService class encapsulates all database operations related to the File2Document model, which links files and documents in the InfiniFlow system. It provides methods to retrieve, insert, update, and delete these associations, along with a utility to find storage locations based on either a file or document ID. This modular design simplifies managing file-document relationships and abstracts underlying database complexities, ensuring consistent and safe data operations.