Basic Read Operations

The read_data() method is the primary way to read data from DealCloud objects. Requests use intapp-rest-client (RestClient); tune timeouts, retries, and concurrency via Advanced configuration.

Basic Usage

from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
)
dc = DealCloud.from_config_object(config)
 
# Read all data from an object
companies = dc.read_data("Company", output="pandas")

⚠️

The output parameter is required. Options: "pandas", "list", "polars", or "polars_lazy".

Output Formats

# Returns pandas.DataFrame
companies = dc.read_data("Company", output="pandas")
 
print(type(companies))  # <class 'pandas.core.frame.DataFrame'>
print(companies.head())

EntryId	CompanyName	Industry	Revenue
12345	Acme Corp	Technology	1000000
12346	Beta Inc	Finance	500000
12347	Gamma LLC	Healthcare	750000

Selecting Fields

Read only specific fields to improve performance:

# Read only specified fields
companies = dc.read_data(
    "Company",
    output="pandas",
    fields=["CompanyName", "Industry", "Revenue"]
)

💡

Always specify fields when you don't need all columns. This reduces data transfer and improves performance.

Filtering with Queries

Apply server-side filters:

# Filter using query syntax
active = dc.read_data(
    "Company",
    output="pandas",
    query="{Status: {$eq: 'Active'}}"
)
 
# Multiple conditions
tech_companies = dc.read_data(
    "Company",
    output="pandas",
    query="{$and: [{Industry: 'Technology'}, {Revenue: {$gt: 1000000}}]}"
)

See Query Syntax for full query documentation.

Parameters

Parameter	Type	Required	Default	Description
`object_id`	`str \| int`	Yes*	-	Object API name or ID
`view_id`	`str \| int`	Yes*	-	View name or ID
`output`	`str`	Yes	-	`"pandas"`, `"list"`, `"polars"`, or `"polars_lazy"`
`fields`	`List[str]`	No	All	Fields to return
`query`	`str`	No	None	Filter query
`resolve`	`str`	No	None	`"name"` or `"id"` (legacy)
`include_nulls`	`bool`	No	`False`	Include null fields (ignored for views, always `False`)
`reference_format`	`ReferenceFormat`	No	`FULL`	How to format references
`reference_cache`	`ReferenceCache`	No	None	Cache for reference lookups

*Either object_id OR view_id must be provided, not both.

⚠️

Views and include_nulls: When reading from views, the include_nulls parameter is automatically set to False, regardless of what you specify. This prevents the API from returning excessive columns (1000+ instead of expected 10-20). See Reading from Views for details.

Working with DataFrames

Filtering

companies = dc.read_data("Company", output="pandas")
 
# Filter after loading
active = companies[companies["Status"] == "Active"]
large = companies[companies["Revenue"] > 1000000]
tech = companies[companies["Industry"].str.contains("Tech", na=False)]

Sorting

# Sort by revenue descending
sorted_companies = companies.sort_values("Revenue", ascending=False)

Exporting

# Export to CSV
companies.to_csv("companies.csv", index=False)
 
# Export to Excel
companies.to_excel("companies.xlsx", index=False)
 
# Export to JSON
companies.to_json("companies.json", orient="records")

Transformations

# Rename columns
companies = companies.rename(columns={
    "CompanyName": "Name",
    "BusinessDescription": "Description"
})
 
# Add calculated column
companies["RevenueM"] = companies["Revenue"] / 1_000_000
 
# Drop columns
companies = companies.drop(columns=["InternalNotes"])

Working with Lists

companies = dc.read_data("Company", output="list")
 
# Iterate
for company in companies:
    print(f"{company['EntryId']}: {company['CompanyName']}")
 
# Filter
active = [c for c in companies if c.get("Status") == "Active"]
 
# Transform
names = [c["CompanyName"] for c in companies]
 
# Convert to DataFrame later if needed
import pandas as pd
df = pd.DataFrame(companies)

Pagination

The SDK handles pagination automatically:

# This reads ALL records, paginating under the hood
all_companies = dc.read_data("Company", output="pandas")
 
# Page size is configurable in DealCloudConfig
# Default: 1000 records per page

Monitoring Progress

# Use progress callback for large reads
def on_progress(current, total):
    print(f"Loaded {current}/{total} records")
 
companies = dc.read_data(
    "Company",
    output="pandas",
    progress_callback=on_progress
)

Example: Complete Read Workflow

from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
)
dc = DealCloud.from_config_object(config)
 
# 1. Read active companies with specific fields
companies = dc.read_data(
    "Company",
    output="pandas",
    fields=["CompanyName", "Industry", "Revenue", "Status", "CreatedDate"],
    query="{Status: 'Active'}"
)
 
# 2. Transform data
companies["Revenue_M"] = companies["Revenue"] / 1_000_000
companies["CreatedDate"] = pd.to_datetime(companies["CreatedDate"])
companies = companies.sort_values("Revenue", ascending=False)
 
# 3. Export results
companies.head(100).to_excel("top_100_companies.xlsx", index=False)
 
print(f"Exported {len(companies)} companies")

Next Steps

Reading from Views - Work with configured views
Query Syntax - Advanced filtering
Streaming Reads - Memory-efficient large reads
Polars Integration - High-performance DataFrame alternative

Overview Reading from Views