Go to: Synopsis. Return value. Keywords. Related. Flags. MEL examples.

Synopsis

referenceQuery [-child] [-dagPath] [-editAttrs] [-editCommand string] [-editNodes] [-editStrings] [-failedEdits boolean] [-filename] [-isExportEdits] [-isLoaded] [-isNodeReferenced] [-isPreviewOnly] [-liveEdits] [-namespace] [-nodes] [-onReferenceNode string] [-parent] [-parentNamespace] [-referenceNode] [-shortName] [-showDagPath boolean] [-showNamespace boolean] [-successfulEdits boolean] [-topReference] [-unresolvedName] [-withoutCopyNumber]

referenceQuery is NOT undoable, NOT queryable, and NOT editable.

Use this command to find out information about references and referenced nodes. A valid target is either a reference node, a reference file, or a referenced node. Some flags don't require a target, see flag descriptions for more information on what effect this has. When a scene contains multiple levels of file references, those edits which affect a nested reference may be stored on several different reference nodes. For example: A.ma has a reference to B.ma which has a reference to C.ma which contains a poly sphere (pSphere1). If you were to open B.ma and translate the sphere, an edit would be stored on CRN which refers to a node named "C:pSphere1". If you were then to open A.ma and parent the sphere, an edit would be stored on BRN which refers to a node named "B:C:pSphere1". It is important to note that when querying edits which affect a nested reference, the edits will be returned in the same format that they were applied. In the above example, opening A.ma and querying all edits which affect C.ma, would return two edits a parent edit affecting "B:C:pSphere1", and a setAttr edit affecting "C:pSphere1". Since there is currently no node named C:pSphere1 (only B:C:pSphere1) care will have to be taken when interpreting the returned information. The same care should be taken when referenced DAG nodes have been parented or instanced. Continuing with the previous example, let's say that you were to open A.ma and, instead of simply parenting pSphere1, you were to instance it. While A.ma is open, "B:C:pSphere1" may now be an amibiguous name, replaced by "|B:C:pSphere1" and "group1|B:C:pSphere1". However querying the edits which affect C.ma would still return a setAttr edit affecting "C:pSphere1" since it was applied prior to B:C:pSphere1 being instanced. Some tips: 1. Use the '-topReference' flag to query only those edits which were applied from the currently open file. 2. Use the '-onReferenceNode' flag to limit the results to those edits where are stored on a given reference node. You can then use various string manipulation techniques to extrapolate the current name of any affected nodes.

Return value

string[]For query execution.

Keywords

reference, attribute, node

Related

file, referenceEdit

Flags

child, dagPath, editAttrs, editCommand, editNodes, editStrings, failedEdits, filename, isExportEdits, isLoaded, isNodeReferenced, isPreviewOnly, liveEdits, namespace, nodes, onReferenceNode, parent, parentNamespace, referenceNode, shortName, showDagPath, showNamespace, successfulEdits, topReference, unresolvedName, withoutCopyNumber
Long name (short name) Argument types Properties
-child(-ch) create
This flag modifies the '-rfn/-referenceNode' and '-f/-filename' flags to indicate the the children of the target reference will be returned. Returns a string array.
-isExportEdits(-iee) create
Returns a boolean indicating whether the specified reference node or file name is an edits file (created with the Export Edits feature)
-isLoaded(-il) create
Returns a boolean indicating whether the specified reference node or file name refers to a loaded or unloaded reference.
-liveEdits(-le) create
Specifies that the edits should be returned based on the live edits database. Only valid when used in conjunction with the editStrings flag.
-dagPath(-dp) create
This flag modifies the '-n/-nodes' flag to indicate that the names of any dag objects returned will include as much of the dag path as is necessary to make the names unique. If this flag is not present, the names returned will not include any dag paths.
-editAttrs(-ea) create
Returns string array. A main flag used to query the edits that have been applied to the target. Only the names of the attributes involved in the reference edit will be returned. If an edit involves multiple attributes (e.g. "connectAttr" edits) the nodes will be returned as separate, consecutive entries in the string array. A valid target is either a reference node, a reference file, or a referenced node. If a referenced node is specified, only those edits which affect that node will be returned. If a reference file or reference node is specified any edit which affects a node in that reference will be returned. If no target is specified all edits are returned. This command can be used on both loaded and unloaded references. By default it will return all the edits, formatted as MEL commands, which apply to the target. This flag can be used in combination with the '-ea/-editAttrs' flag to indicate that the names of both the involved nodes and attributes will be returned in the format 'node.attribute'.
-editNodes(-en) create
Returns string array. A main flag used to query the edits that have been applied to the target. Only the names of the nodes involved in the reference edit will be returned. If an edit involves multiple nodes (e.g. "connectAttr" edits) the nodes will be returned as separate, consecutive entries in the string array. A valid target is either a reference node, a reference file, or a referenced node. If a referenced node is specified, only those edits which affect that node will be returned. If a reference file or reference node is specified any edit which affects a node in that reference will be returned. If no target is specified all edits are returned. This command can be used on both loaded and unloaded references. By default it will return all the edits, formatted as MEL commands, which apply to the target. This flag can be used in combination with the '-ea/-editAttrs' flag to indicate that the names of both the involved nodes and attributes will be returned in the format 'node.attribute'.
-editStrings(-es) create
Returns string array. A main flag used to query the edits that have been applied to the target. The edit will be returned as a valid MEL command. A valid target is either a reference node, a reference file, or a referenced node. If a referenced node is specified, only those edits which affect that node will be returned. If a reference file or reference node is specified any edit which affects a node in that reference will be returned. If no target is specified all edits are returned. This command can be used on both loaded and unloaded references. By default it will return all the edits, formatted as MEL commands, which apply to the target. This flag cannot be used with either the '-en/-editNodes' or '-ea/-editAttrs' flags.
-failedEdits(-fld) boolean create
This is a secondary flag used to indicate whether or not failed edits should be acted on (e.g. queried, removed, etc...). A failed edit is an edit which could not be successfully applied the last time its reference was loaded. An edit can fail for a variety of reasons (e.g. the referenced node to which it applies was removed from the referenced file). By default failed edits will not be acted on.
-filename(-f) create
Returns string. A main flag used to query the filename associated with the target reference.
-isNodeReferenced(-inr) create
Returns boolean. A main flag used to determine whether or not the target node comes from a referenced file. true if the target node comes from a referenced file, false if not.
-isPreviewOnly(-ipo) create
Returns boolean. This flag is used to determine whether or not the target reference node is only a preview reference node.
-namespace(-ns) create
Returns string. This flag returns the full namespace path of the target reference, starting from the root namespace ":". It can be combined with the shortName flag to return just the base name of the namespace.
-nodes(-n) create
Returns string array. A main flag used to query the contents of the target reference.
-parent(-p) create
This flag modifies the '-rfn/-referenceNode' and '-f/-filename' flags to indicate the the parent of the target reference will be returned.
-parentNamespace(-pns) create
A main flag used to query and return the parent namespace of the target reference.
-referenceNode(-rfn) create
Returns string. A main flag used to query the reference node associated with the target reference.
-shortName(-shn) create
This flag modifies the '-f/-filename' and '-ns/-namespace' flags. Used with the '-f/-filename' flag indicates that the file name returned will be the short name (i.e. just a file name without any directory paths). If this flag is not present, the full name and directory path will be returned. Used with the '-ns/-namespace' flag indicates that the namespace returned will be the base name of the namespace. (i.e. the base name of the full namespace path ":AAA:BBB:CCC" is "CCC" )
-showDagPath(-sdp) boolean create
Shows/hides the full dag path for edits. If false only displays the node-name of reference edits. Must be used with the -editNodes, -editStrings or -editAttrs flag.
-showNamespace(-sns) boolean create
Shows/hides the namespaces on nodes in the reference edits. Must be used with the -editNodes, -editStrings or -editAttrs flag
-successfulEdits(-scs) boolean create
This is a secondary flag used to indicate whether or not successful edits should be acted on (e.g. queried, removed, etc...). A successful edit is any edit which was successfully applied the last time its reference was loaded. By default successful edits will be acted on.
-topReference(-tr) create
This flag modifies the '-rfn/-referenceNode' flag to indicate the top level ancestral reference of the target reference will be returned.
-unresolvedName(-un) create
This flag modifies the '-f/-filename' flag to indicate that the file name returned will be unresolved (i.e. it will be the path originally specified when the file was loaded into Maya; this path may contain environment variables and may not exist on disk). If this flag is not present, the resolved name will be returned.
-withoutCopyNumber(-wcn) create
This flag modifies the '-f/-filename' flag to indicate that the file name returned will not have a copy number (e.g. '{1}') appended to the end. If this flag is not present, the file name returned may have a copy number appended to the end.
-editCommand(-ec) string createquerymultiuse
This is a secondary flag used to indicate which type of reference edits should be considered by the command. If this flag is not specified all edit types will be included. This flag requires a string parameter. Valid values are: "addAttr", "connectAttr", "deleteAttr", "disconnectAttr", "parent", "setAttr", "lock" and "unlock". In some contexts, this flag may be specified more than once to specify multiple edit types to consider.
-onReferenceNode(-orn) string createquerymultiuse
This is a secondary flag used to indicate that only those edits which are stored on the indicated reference node should be considered. This flag only supports multiple uses when specified with the "exportEdits" command.
Flag can appear in Create mode of command Flag can appear in Edit mode of command
Flag can appear in Query mode of command Flag can be used more than once in a command.

MEL examples

// Build a sample scene:
// main scene contains a reference to mid.ma.
// mid.ma contains a reference to bot.ma.
// Create bot.ma with a poly sphere.
//
polySphere;
file -rename "bot.ma";
file -f -type "mayaAscii" -save;
// Create mid.ma with a poly cone.
// Reference bot.ma into mid.ma and group
// the sphere in bot.ma
//
file -f -new;
file -r -ns "bot" "bot.ma";
polyCone;
group bot:pSphere1;
file -rename "mid.ma";
file -f -type "mayaAscii" -save;
// Create a poly plane.
// Reference mid.ma into the main scene,
// move the cone in mid.ma, and connect
// the plane to the sphere in bot.ma.
//
file -f -new;
file -r -ns "mid" "mid.ma";
select -r mid:pCone1;
move -r 5 5 5;
polyPlane;
connectAttr pPlane1.ty mid:bot:polySphere1.radius;
// Now perform some queries:
//
referenceQuery -filename midRN;
// Result: C:/Documents and Settings/user/My Documents/maya/projects/default/scenes/mid.ma
referenceQuery -filename -shortName mid:pCone1;
// Result: mid.ma
referenceQuery -filename -parent mid:botRN;
// Result: C:/Documents and Settings/user/My Documents/maya/projects/default/scenes/mid.ma
referenceQuery -referenceNode mid.ma;
// Result: midRN
referenceQuery -referenceNode "C:/Documents and Settings/user/My Documents/maya/projects/default/scenes/bot.ma";
// Result: mid:botRN
referenceQuery -referenceNode -parent bot.ma;
// Result: midRN
referenceQuery -referenceNode -topReference bot.ma;
// Result: midRN
referenceQuery -nodes mid:botRN;
// Result: mid:bot:pSphere1 mid:bot:pSphereShape1 mid:bot:lightLinker1 mid:bot:layerManager mid:bot:defaultLayer mid:bot:renderLayerManager mid:bot:defaultRenderLayer mid:bot:polySphere1 mid:bot:uiConfigurationScriptNode mid:bot:sceneConfigurationScriptNode
referenceQuery -isNodeReferenced pPlane1;
// Result: 0
referenceQuery -isNodeReferenced mid:pCone1;
// Result: 1
referenceQuery -parentNamespace mid:botRN;
// Result: mid
referenceQuery -parentNamespace mid:bot:pSphere1;
// Result: mid
referenceQuery -parentNamespace "C:/Documents and Settings/user/My Documents/maya/projects/default/scenes/bot.ma";
// Result: mid
referenceQuery -namespace bot.ma;
// Result: :mid:bot //
referenceQuery -namespace mid:botRN;
// Result: :mid:bot //
referenceQuery -namespace -shortName bot.ma;
// Result: bot //
referenceQuery -namespace mid.ma;
// Result: :mid //
referenceQuery -namespace -shortName mid.ma;
// Result: mid //