SuiteQL Metadata vs SuiteCloud XML for Custom Records

Two common ways to inspect NetSuite custom-record definitions look similar in conversation and very different in practice:

SuiteQL against analytics metadata exposed by the Records Catalog.
SuiteCloud Development Framework (SDF) object XML imported with SuiteCloud CLI or the IDE.

This comparison sits beside How to Query NetSuite Custom Record Fields With SuiteQL and SuiteCloud: Import a Custom Record and Its Custom Fields. It helps you pick the right tool—and avoid treating one system’s names as the other’s schema.

Side-by-side

Concern	SuiteQL + Records Catalog	SuiteCloud object XML
Primary job	Analytical discovery and reporting	Deployment, source control, account promotion
Source of truth for identifiers	Account catalog, SuiteScript and REST Query API channel	SDF object definitions and script IDs
Custom field representation	Analytical record/columns if exposed (often discussed as `CustomRecordCustomField`-style metadata)	Nested `<customrecordcustomfield>` under `<customrecordtype>`
Availability	Role-, feature-, channel- and account-specific	Governed by SDF preferences, features in `manifest.xml`, and import permissions
Instance data	Separate queries to `customrecord_...`	Not the purpose of type object XML
Good for	Data dictionaries, “what fields exist for reporting?”	Moving types/fields between accounts, reviewing full object config
Weak for	Guaranteeing every UI property as a queryable column	Ad-hoc analytics joins and large cross-type reports

Neither surface is a complete substitute for the other.

SuiteQL metadata: definitions for analytics

SuiteQL answers questions like:

Which field definitions are visible to this role through the analytics channel?
What script IDs and labels can I project in a dictionary extract?
Can I join field definitions to type definitions when the catalog documents a join?

Workflow:

Setup → Records Catalog, SuiteScript and REST Query API channel.
Confirm record and field IDs (find table and field names).
Query progressively (pillar guide, column reference).
Export with paging when needed (SuiteScript data dictionary export).

Illustrative shape only:

SELECT
    field_definition.id,
    field_definition.scriptid,
    field_definition.label
FROM
    CustomRecordCustomField field_definition
ORDER BY
    field_definition.scriptid

If that record is absent, SuiteQL is the wrong place to force a definition dump—see Why CustomRecordCustomField Is Missing From SuiteQL.

SuiteCloud XML: definitions for deployment

SDF object XML answers questions like:

What is the full object definition to store in git?
How do I promote a custom record type and its fields to another account?
Which XML elements describe field types, selects and display settings for deployment?

Illustrative import:

suitecloud object:import \
  --type customrecordtype \
  --scriptid customrecord_example \
  --destinationfolder /Objects

Illustrative nesting (structure only; real files are larger):

<customrecordtype scriptid="customrecord_example">
  <recordname>Example</recordname>
  <customrecordcustomfields>
    <customrecordcustomfield scriptid="custrecord_example_status">
      <label>Status</label>
      <!-- additional deployment properties as generated for the account -->
    </customrecordcustomfield>
  </customrecordcustomfields>
</customrecordtype>

Searching an imported file for customrecordcustomfield finds XML elements, not SuiteQL tables. Element names and analytical record IDs can look related and still not be interchangeable join keys.

Oracle documents importing account components into SuiteCloud projects; an import with the same script ID overwrites the project object—review the diff before you commit. Prefer Oracle NetSuite documentation for CLI flags and behaviour.

Naming collisions that cause confusion

String you see	Often means in SDF	Often means in SuiteQL discussions
`customrecordcustomfield`	XML element for a field on a type object	Informal name for field-definition metadata
`CustomRecordCustomField`	Rarely an SDF type name in the same way	Possible analytical record script ID if catalog lists it
`customrecordtype`	SDF object type / XML root	Possible analytical type metadata if catalog lists it
`scriptid`	Object and field script IDs in XML	Analytical column when exposed under that ID

Always ask: “Is this an SDF identifier, a UI label, or a Records Catalog script ID?”

Choosing a path

Goal	Prefer
Build a reporting data dictionary of exposed field definitions	SuiteQL + catalog (+ SuiteScript export)
Move a custom record and fields between accounts	SuiteCloud object import/deploy
Debug “unknown identifier” in SuiteQL	Catalog role/channel checklist—not XML edits
Review select/record and display properties for deployment	SDF XML (and UI); only use SuiteQL if those properties are catalog-exposed
Read stored values on rows	Instance SuiteQL / searches / APIs—not definition XML and not definition-only metadata
Join field definitions to type script IDs in SQL	SuiteQL only with a catalog-documented join (join guide)

Combined workflow many teams use

Design in a sandbox UI.
Capture deployment truth with SuiteCloud import into the project.
Discover analytics IDs in the Records Catalog for integrations and dictionaries.
Query instance data with confirmed customrecord_... / custrecord_... IDs.
Re-check the catalog when roles or features change—even if XML has not changed.

XML stability does not guarantee analytics exposure; analytics exposure does not replace a deployable object definition.

Caveats

Records Catalog results are account-, feature-, role- and channel-specific.
Do not invent SuiteQL joins from XML parent/child nesting.
Do not invent SDF structure from SuiteQL result columns.
Custom-record instance tables are a third surface, distinct from both definition metadata and SDF type objects.
Examples here are illustrative; verify CLI flags, object types and analytical IDs against current Oracle docs and your catalog.