plugins/org.eclipse.mat.ui.help/reference/oqlsyntaxselect.dita

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Copyright (c) 2008, 2023 SAP AG and IBM Corporation.
    All rights reserved. This program and the accompanying materials
    are made available under the terms of the Eclipse Public License 2.0
    which accompanies this distribution, and is available at
    https://www.eclipse.org/legal/epl-2.0/
    
    SPDX-License-Identifier: EPL-2.0
   
    Contributors:
        SAP AG - initial API and implementation
        Andrew Johnson (IBM Corporation) - enhancements
 -->
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd" >
<reference id="ref_oqlsyntaxselect" xml:lang="en-us">
	<title>SELECT Clause</title>
	<shortdesc />

	<prolog>
		<copyright>
			<copyryear year=""></copyryear>
			<copyrholder>
				Copyright (c) 2008, 2023 SAP AG and others.
			    All rights reserved. This program and the accompanying materials
			    are made available under the terms of the Eclipse Public License 2.0
			    which accompanies this distribution, and is available at
			    https://www.eclipse.org/legal/epl-2.0/
			</copyrholder>
		</copyright>
	</prolog>

	<refbody>
		<section>
			<p>
				The <codeph>SELECT</codeph> clause determines what to extract from the
				heap dump. To display objects and be able to browse the
				outgoing references, use the
				<codeph>*</codeph>
				symbol:
			</p>
			<codeblock>SELECT * FROM java.lang.String</codeblock>

			<p><b>Select specific columns</b></p>
			<p>
				Alternatively, one can select the fields to be
				displayed:
			</p>
			<codeblock>SELECT toString(s), s.count, s.value FROM java.lang.String s</codeblock>
			<p>
				The resulting table knows about the underlying object.
				So you can use the context menu to open further views on
				the object at hand. Use the <codeph>@</codeph> symbol to access Java
				attributes and methods of the objects. There are also a
				number of built-in functions available to extract common
				information:
			</p>
			<codeblock>SELECT toString(s), s.@usedHeapSize,
    s.@retainedHeapSize FROM java.lang.String s</codeblock>
			<p>
				The section on
				<xref href="propertyaccessors.dita">
					Property Accessors
				</xref>
				contains details on the commonly available attributes.
			</p>
			<p><b>Provide column names</b></p>
			<p>Use the AS keyword to name the columns:</p>
			<codeblock>SELECT toString(s) AS Value,
    s.@usedHeapSize AS "Shallow Size",
    s.@retainedHeapSize AS "Retained Size"
			FROM java.lang.String s</codeblock>
			<p>
				Use the
				<codeph>AS RETAINED SET</codeph>
				keyword to get the set of objects retained by your
				selection:
			</p>
			<codeblock>SELECT AS RETAINED SET * FROM java.lang.String</codeblock>
			<p><b>Flatten select items into an object list</b></p>
			<p>
				Use the
				<codeph>OBJECTS</codeph>
				to interpret the items in the
				<codeph>SELECT</codeph>
				clause as objects:
			</p>
			<codeblock>SELECT OBJECTS dominators(s) FROM java.lang.String s</codeblock>
			<p>
				The function
				<codeph>dominators()</codeph>
				returns an array of objects. Therefore the query returns
				a list of object lists, i.e. arrays. By using the
				keyword
				<codeph>OBJECTS</codeph>
				, we force the OQL to reduce this into a single list of
				objects.
			</p>
			<p><b>Select unique objects</b></p>
			<p>
				Use the
				<codeph>DISTINCT</codeph>
				keyword to only select unique objects:
			</p>
			<codeblock>SELECT DISTINCT * FROM OBJECTS 0,1,1,2</codeblock>
			<p>
				Use the
				<codeph>DISTINCT OBJECTS</codeph>
				keyword to only select unique objects from the result of the selected clause:
			</p>
			<codeblock>SELECT DISTINCT OBJECTS classof(s) FROM java.lang.String s</codeblock>
			<p>
				The function
				<codeph>classof</codeph>
				returns the class object. Of course, all Strings have
				the same class. The <codeph>OBJECTS</codeph> converts the underlying row with a String object
				and a displayed value of the class object
				to the object represented by the result of the <codeph>classof</codeph> function.
				Without the <codeph>DISTINCT OBJECTS</codeph>
				keywords, the query would result in a list with as many
				rows with the same class as there are Strings.
			</p>
			<p>With Memory Analyzer 1.10 or later, <codeph>DISTINCT</codeph> also operates without
			<codeph>OBJECTS</codeph> to find items which are distinct.
			See <xref format="html" scope="peer" href="https://wiki.eclipse.org/MemoryAnalyzer/OQL#SELECT_DISTINCT">Wiki: OQL SELECT DISTINCT</xref>
			for further details.</p>
			<p><b>Expressions (experimental, Memory Analyzer 1.4 or later)</b></p>
			<p>
				Use the expressions for the select item, including string concatenation:
			</p>
			<codeblock>SELECT s.@objectId, s.@objectId * 2, "The object ID is "+@objectId FROM OBJECTS 0,1,1,2 s</codeblock>
			<p>
				With Memory Analyzer 1.4 or later expressions and sub-selects are allowed for select items. More complex
				expressions may need to be parenthesized. This is currently in the test phase.
			</p>
		</section>
	</refbody>
</reference>