How To insert_rows() in DataversePython

How to Use the insert_rows() Method in DataversePython

The insert_rows() method in the DataverseClient class allows you to insert data from a pandas DataFrame into a Microsoft Dataverse entity. This article explains its usage, parameters, and provides practical examples to help you get started.

---

What is insert_rows()?

The insert_rows() method lets you add multiple records to any Dataverse entity (such as accounts, contacts, or custom tables) by passing a pandas DataFrame. Each row in the DataFrame is sent as a new record to Dataverse.

---

Method Signature

insert_rows(
    entity: str,
    df: pd.DataFrame
) -> None

---

Parameters Explained

• entity (str, required):
  The plural name of the Dataverse entity you want to insert into (e.g., 'accounts', 'contacts').
• df (pd.DataFrame, required):
  The DataFrame containing the rows to insert. Each column should match a field in the entity schema.

---

Basic Example: Insert New Accounts

from DataversePython.DataverseClient import DataverseClient
import pandas as pd

# Initialize the client with your configuration file
prod = DataverseClient('sample_config.json')

# Create a DataFrame with new account data
new_accounts = pd.DataFrame([
    {"name": "Contoso Ltd", "emailaddress1": "info@contoso.com"},
    {"name": "Fabrikam Inc", "emailaddress1": "contact@fabrikam.com"}
])

# Insert the new accounts
prod.insert_rows(entity='accounts', df=new_accounts)

---

Example: Insert Contacts with Basic Fields

# Create a DataFrame for new contacts
contacts = pd.DataFrame([
    {"firstname": "Alice", "lastname": "Smith", "emailaddress1": "alice.smith@example.com"},
    {"firstname": "Bob", "lastname": "Jones", "emailaddress1": "bob.jones@example.com"}
])

prod.insert_rows(entity='contacts', df=contacts)

---

Example: Insert Contacts with Optionset Fields

# Example: Insert contacts with an optionset (choice) field
        # Assume 'preferredcontactmethodcode' is an optionset field (e.g., 1=Email, 2=Phone)
        contacts_optionset = pd.DataFrame([
            {"firstname": "Charlie", "preferredcontactmethodcode": 1},
            {"firstname": "Dana", "preferredcontactmethodcode": 2}
        ])

        prod.insert_rows(entity='contacts', df=contacts_optionset)
        

---

Example: Insert Contacts with Lookup Field (parentcustomerid)

# Example: Insert contacts with a lookup field (parentcustomerid)
        # The parentcustomerid field can reference an account or contact (customer lookup)
        # Use the format: {'parentcustomerid_{entity}@odata.bind': '/accounts()'}
        contacts_lookup = pd.DataFrame([
            {
                "firstname": "Eve",
                "lastname": "Adams",
                "emailaddress1": "eve.adams@example.com",
                "parentcustomerid_accounts@odata.bind": "/accounts(00000000-0000-0000-0000-000000000001)"
            },
            {
                "firstname": "Frank",
                "lastname": "Miller",
                "emailaddress1": "frank.miller@example.com",
                "parentcustomerid_contacts@odata.bind": "/contacts(00000000-0000-0000-0000-000000000002)"
            }
        ])

        prod.insert_rows(entity='contacts', df=contacts_lookup)
        

---

Example: Insert Contacts with Multi-Lookup Field

# Example: Insert contacts with a multi-lookup field
        # Assume 'new_multilookupfield' is a custom multi-lookup field (e.g. 1=training,2=consulting,3=developing)  
        contacts_multilookup = pd.DataFrame([
            {
                "firstname": "Grace",
                "lastname": "Hopper",
                "emailaddress1": "grace.hopper@example.com",
                "new_multilookupfield": "1, 3"
            }
        ])

        prod.insert_rows(entity='contacts', df=contacts_multilookup)
        

---

Notes and Best Practices

• Each row in the DataFrame is sent as a separate POST request to Dataverse.
• If a row fails to insert, the method logs an error (including the error code and response) to DataverseClient.log.
• Make sure your DataFrame columns match the entity's schema in Dataverse.
• For large inserts (more than 50k rows), consider batching in multiple DataFrames.
• A insert_rows_batch() is already on the roadmap 😉

---

Error Handling

If an insertion fails (e.g., due to validation or permission issues), an error is logged to DataverseClient.log and the method continues with the next row. Always check this log file for troubleshooting.

---

Tips

• Always use the plural form of the entity name (e.g., 'accounts', not 'account').
• Refer to the Microsoft Dataverse Web API documentation for field names and data types.
• Use the VSCode DataWrangler Extension and Jupyter notebooks for interactive data preparation.

---

Conclusion

The insert_rows() method makes it easy to add new records to Dataverse entities from pandas DataFrames, enabling seamless integration between Python and Microsoft Dataverse for automation and data migration scenarios.

Happy coding!