Copying Objects#
Serverless ADR supports copying collections of report objects—including Items, Templates, Sessions, and Datasets—from one database to another. This functionality facilitates data migration, backup, synchronization, or environment replication.
Copying ensures that GUIDs (unique identifiers) are preserved and that related Sessions and Datasets referenced by Items are copied as well to maintain data integrity.
Prerequisites#
Multiple database configurations must be set up in the ADR instance.
The source and target databases must be properly configured and accessible.
For objects referencing media files (e.g., images, animations), a valid media directory must be specified for the target database.
Only top-level Templates (those without parents) can be copied; their children are copied recursively.
API Usage#
Use the copy_objects()
method on an ADR instance:
count = adr.copy_objects(
object_type=Item, # Class of objects to copy (Item, Template, Session, Dataset)
target_database="dest", # Target database key
query="A|i_tags|cont|project=wing_sim;", # ADR query string to filter objects
target_media_dir="/path/to/media", # Required if copying Items with media in SQLite
test=False, # If True, only logs number of objects to be copied, no actual copy
)
print(f"Copied {count} objects.")
Parameters#
object_type
(type): The class of objects to copy. Must be a subclass ofItem
,Template
,Session
, orDataset
.target_database
(str): The configured target database key.query
(str, optional): ADR query string to select which objects to copy. Defaults to copying all.target_media_dir
(str or Path, optional): Directory to copy media files to when copying Items.test
(bool, optional): If True, no copying occurs; only the count of matching objects is returned.
Copying Logic Details#
Validation
Checks that
object_type
is valid.Validates that both source (“default”) and target databases exist in ADR’s configuration.
Querying Objects
Uses the ADR query interface to fetch objects matching the query string.
Handling Items
Checks if any Items reference media files.
Determines the target media directory: - Uses provided
target_media_dir
if specified. - If using SQLite for the target DB, attempts to resolve the media directory adjacent to the DB. - Throws an exception if no suitable media directory can be determined.For each Item, attempts to fetch or create the corresponding Session and Dataset in the target DB.
Updates Items to reference the copied Sessions and Datasets.
Handling Templates
Only copies top-level Templates.
Recursively copies child Templates preserving hierarchy and order.
Handling Sessions and Datasets
Copies queried Sessions or Datasets as-is.
Test Mode
If
test=True
, logs and returns the number of objects that would be copied, without performing any write operations.
Performing Copy
Saves all copied objects to the target database.
Copies media files referenced by Items to the target media directory.
Rebuilds 3D geometry files if applicable.
Example: Copy Sessions
session_count = adr.copy_objects(
object_type=Session,
target_database="dest",
query="A|s_tags|cont|dp=;",
)
print(f"Copied {session_count} sessions.")
Example: Copy Items with Media
item_count = adr.copy_objects(
Item,
target_database="dest",
query="A|i_tags|cont|dp=dp227;",
target_media_dir=r"C:\ansys\dest_db\media",
)
print(f"Copied {item_count} items with media.")
Example: Copy Top-Level Template and Its Children
template_count = adr.copy_objects(
Template,
target_database="dest",
query="A|t_name|eq|Serverless Simulation Report;",
)
print(f"Copied {template_count} templates.")
Error Handling#
Raises
TypeError
ifobject_type
is not a valid ADR model subclass.Raises
ADRException
if databases are misconfigured.Raises
ADRException
if attempting to copy non top-level Templates.Raises
ADRException
iftarget_media_dir
is missing when required.Exceptions from saving or media copying are caught and re-raised as
ADRException
.
Implementation Notes#
The copying uses a deep copy of Template objects to preserve the hierarchy.
For Items, Session and Dataset references are fetched or created in the target database to maintain links.
Media files are copied using standard filesystem operations; ensure appropriate permissions.
The method supports extensions for future support of source database selection (currently hardcoded to “default”).
Best Practices#
Ensure the target database is properly configured and accessible before copying.
Copy related sessions and datasets automatically by copying items.
Always use
test=True
initially to preview the number of objects to be copied.Ensure media directories have sufficient space and permissions.
Use descriptive ADR query strings to limit copy scope.
Avoid copying Templates with parents; copy only top-level templates to prevent hierarchy issues.
Call
adr.setup()
before copying to ensure proper configuration.
Summary#
The copy_objects()
method provides robust, automated transfer of ADR report content and metadata between databases, preserving references and media assets to support backup, migration, and distributed workflows.
Next Steps#
Learn how to manage unwanted data after copying with Deleting Objects.