Embedded SuiteScript Developers

Email
Topaz Harbor

Insights

NetSuite 2026.1: Primary Record Filtering and SuiteQL Address Joins

NetSuite 2026.1 stops allowing mismatched address-table joins in SuiteQL. Here is what changed, why it matters, and how to audit your queries before the upgrade.

Contact View Services

NetSuite 2026.1: Primary Record Filtering and SuiteQL Address Joins

For years, NetSuite developers have had to navigate a confusing set of dozens of address-related tables.

Tim Dietrich’s SuiteQL table reference is a useful reminder of just how many there are.

Part of the confusion came from the fact that NetSuite often let those address tables behave more like loosely filtered global views than strictly scoped record-specific tables.

That meant you could sometimes join a record to an address table that did not appear to belong to that record type at all, and the query would still work as long as the key lined up.

NetSuite 2026.1 changes that.

The Old Behavior

In earlier releases, many address joins were more permissive than the schema implied.

For example, this query can work in NetSuite 2025.2 even though it joins a Location record to an Employee address table:

SELECT
  loc.name AS name,
  addr.nkey AS nkey,
  addr.city AS city,
  addr.state AS state,
  addr.zip AS zip
FROM location loc
JOIN employeeAddressbookEntityAddress addr
  ON loc.mainaddress = addr.nkey
WHERE loc.id = 123

That is not the only mismatch that used to work.

We also confirmed working joins in 2025.2 against tables such as:

  • companyaddressbookentityaddress
  • subsidiarymainaddress
  • workplacemainaddress

In practice, NetSuite was allowing developers to treat several of these address tables as if they were interchangeable.

What Changed in 2026.1

With NetSuite 2026.1, that behavior is gone.

NetSuite now enforces what appears to be Primary Record Filtering on these address views.

In practical terms, these tables no longer behave like open global address tables. They now behave more like private views scoped to the record type they were designed for.

Examples:

  • employeeAddressbookEntityAddress is now scoped to Employees
  • customerAddressbookEntityAddress is now scoped to Customers
  • location-related address access must use the proper location address path

So the earlier query against employeeAddressbookEntityAddress will now return no rows or fail, even though it used to work in 2025.2.

If you want the main address for a Location in 2026.1, you now need to use the correct table for that record path, such as locationmainaddress.

Why This Is Actually Better

This can absolutely break legacy code, but it is still the right direction.

The old behavior was convenient, but it also made the schema less trustworthy.

When unrelated address views can be used interchangeably, you get:

  • weaker mental models for how the schema actually works
  • queries that succeed for the wrong reasons
  • more risk that joins bypass the intent of record-level data boundaries

By enforcing proper record-specific paths, NetSuite improves both data privacy and schema integrity.

That is a net positive, even if it creates cleanup work today.

What Developers Should Do Now

Do not wait for the production upgrade window to discover this.

Start with these three steps:

1. Audit Address Joins

Search your SuiteQL and script code for joins where the record type does not match the address table name.

Examples of risk patterns:

  • Location joined to an Employee address table
  • Subsidiary joined through a different record type’s address view
  • any join that “works” only because nkey happens to match

If the join looks clever, inherited, or suspiciously generic, inspect it closely.

2. Follow the Real Record Path

In 2026.1, you should assume NetSuite expects you to follow the proper path:

Parent record -> Addressbook -> Address subrecord

That means choosing the address table that actually belongs to the record you are querying, rather than relying on a broader address table that used to return the same data.

If you are querying a Location, use the Location address path.

If you are querying an Employee, use the Employee address path.

That is the safer long-term rule now.

3. Test Before the Upgrade Lands

You do not need to wait for production to validate your cleanup.

Use your current 2025.2 environment or a Sandbox to identify the mismatched joins now, replace them with the correct record-specific path, and confirm the revised query still returns what the business expects.

The important shift is not just “make the query pass.”

It is “make the query correct under the stricter schema behavior NetSuite is enforcing.”

Practical Takeaway

If you have older SuiteQL that joins address tables loosely based on nkey, assume it is at risk in 2026.1.

What used to behave like a reusable address view now appears to be filtered by the primary record type the table was designed for.

That means this is a good time to audit your joins, clean up schema assumptions, and make the relationship path explicit before the upgrade forces the issue.

Where Topaz Harbor Fits

This is exactly the kind of release-change cleanup that tends to hide in mature NetSuite environments:

  • queries that have “always worked”
  • inherited reporting logic nobody wants to touch
  • data assumptions that only surface during release testing

If your team wants help auditing SuiteQL and NetSuite customization risk ahead of an upgrade, review our Services or start on the Contact page.